Connect an MCP Client

Every ObjectStack deployment is already an MCP server. The runtime serves the Model Context Protocol at /api/v1/mcp — on by default, no plugin to install, no configuration step. Your objects and exposed actions become typed tools the moment you define them; this page is about the only thing left to do: connecting a client and proving it works.

Claude Code (one command)

Interactive clients use OAuth — each deployment is its own OAuth 2.1 authorization server, so there are no admin-minted credentials to pass around. The first tool call opens a browser login and you connect as yourself:

# local dev server
claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp

# a deployed instance
claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp

For headless use (CI, containers) skip OAuth and attach an API key instead:

claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp \
  --header "x-api-key: osk_..."

Claude Desktop and claude.ai

Settings → Connectors → Add custom connector, then paste the MCP URL (https://your-deployment.example.com/api/v1/mcp). The first use walks through the same browser login.

Any MCP client (.mcp.json)

Clients that read an mcpServers map connect the same way. With an API key:

{
  "mcpServers": {
    "objectstack": {
      "type": "http",
      "url": "https://your-deployment.example.com/api/v1/mcp",
      "headers": { "x-api-key": "osk_..." }
    }
  }
}

Headless: API keys

Mint a key from Setup → Connect an Agent in the Console (which also shows copy-paste-ready connect snippets per client), or over REST:

curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys
# → { "key": "osk_..." }  — shown once; store it in your secret manager

Send it on every request in any of three equivalent forms:

What the agent gets

Ten data and action tools, generated from your metadata:

Two exposure rules to know:

• Objects are exposed automatically — except sys_* system objects, which are blocked fail-closed.
• Actions require the author's opt-in: ai: { exposed: true } plus an ai.description of at least 40 characters, and the action must be callable without a UI (script with a body or registered handler, or flow). See Actions as Tools and Actions.

The security model

• Every call runs as the caller. The MCP bridge resolves the same ExecutionContext as a REST request, so RBAC, row-level security, and field-level security apply to the agent exactly as they do to a person in the Console. Sparse results or denied writes usually mean governance is working, not that the connection is broken.
• OAuth scopes narrow the toolset. Tokens carry data:read, data:write, and actions:execute scopes — tools outside the granted scopes are not even registered for that session. API-key and session callers get the full set, still permission-checked per call.
• Action bodies run as trusted app code once invoked (the ai.exposed gate and requiredPermissions are checked at invoke time). Treat writing an action as a code-review-worthy act — that's the real security boundary.
• An action can also declare ai.requiresConfirmation; destructive-looking actions (confirmText, danger variants) default to requiring it.

Verify the connection

Ask the agent something only the live schema can answer:

"What objects does this app have, and what fields does the main one carry?"

You should see list_objects and describe_object fire. The natural working pattern for an agent is list_objects → describe_object → query_records → run_action — if all four work, the connection is fully operational.

Agents work noticeably better with the app's skill file: download it from GET /api/v1/mcp/skill, or install the official Claude plugin (claude plugin marketplace add objectstack-ai/claude-plugin) which bundles the skill and a guided /objectstack:connect command.

Troubleshooting

Related

• Actions as Tools — the run_action bridge and its governance
• Actions — defining the actions you expose
• Your app as an MCP server — the API-level view
• AI Agents — building agents inside your app (the other direction)