MCP client setup — Claude, Cursor and IDEs

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

Then open a new Claude Code session and run /mcp — pick the server and choose Authenticate to complete the browser login. Two things to expect on this track:

• Until that login has happened, claude mcp list / claude mcp get my-app report the server as ✘ Failed to connect. That is the health probe being answered with a 401, not a broken setup — the status flips once the session is authenticated.
• A Claude Code session that was already running when you ran claude mcp add does not pick the server up; start a fresh one.

For headless use (CI, containers), or whenever you would rather not go through the browser login, skip OAuth and attach an API key instead — with a key the server reports ✔ Connected immediately, no login step:

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

claude mcp add registers the server at local scope by default — visible only from the directory you ran it in. Add -s user to make it available from every project.

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 the Connect an Agent page in the Console. One page, two doors — which one you have depends on your permissions:

• Any signed-in user — open the avatar menu (top right) → Profile to enter the Account app, then Developer → Connect an Agent in its sidebar. Direct link: /_console/apps/com.objectstack.account/page/connect_agent.
• Platform admins — Setup → Connect an Agent, at /_console/apps/com.objectstack.setup/page/connect_agent, reached from the Setup sidebar. The Setup app requires the setup.access permission, so this door alone is not enough for an ordinary member; the Account one needs none.

On the page, the Create key button sits at the bottom under API keys. The new key is shown once, together with a ready-to-paste x-api-key: osk_... header line — copy it before you dismiss the panel. The same page carries copy-paste connect snippets for Claude Code, Claude Desktop, Cursor, VS Code, and Codex, and a download link for the app's SKILL.md.

Your own keys are listed (prefix only) and revoked under Account → Developer → API Keys. Platform admins get the tenant-wide list at Setup → Access Control → API Keys, which requires manage_platform_settings.

Or mint one over REST:

curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys
# → { "success": true, "data": { "key": "osk_...", "prefix": "osk_...", "name": "API Key",
#                                "expires_at": "2027-01-12T09:30:00.000Z" } }
#   the raw key is shown once — store it in your secret manager

Key lifetime, inactivity and rotation

Personal API keys do not live forever. The policy is part of the Authentication settings (the auth namespace, group API keys), with these defaults:

• Creating a key. Pass { "expires_at": "<ISO date>" } to choose the expiry. A date further away than the maximum is refused with 400 API_KEY_EXPIRY_TOO_LONG, whose message names the latest date allowed; exactly the maximum is accepted. Without expires_at the key gets the default lifetime, and the response echoes the date it got.
• Use is recorded. Each key's last_used_at is stamped when the key is used (at most once an hour) and shows on the API Keys page.
• Keys created before the policy. A key that was created with no expiry date gets one year of grace from the moment the deployment started enforcing the policy (recorded once, as api_key_policy_started_at). The date is written onto the key's expires_at the first time it is used, so the API Keys page shows it, and the refusal after it names it. A key with no recorded use counts its inactivity from that same moment (or from its own creation, when that is later).

A key that stops working is refused with 403 and a code that says why — the message names the key's prefix, the date, and the remedy:

The remedy is the same for all three: create a new key and replace the old one wherever it is configured — keys do not renew. To rotate without a gap, create the new key first, switch the integration over, then revoke the old one. An unknown key (a typo, a key that never existed) still gets the generic 401 UNAUTHENTICATED.

These codes reach the caller on every endpoint that accepts a key: the MCP HTTP endpoint (/api/v1/mcp) and the other endpoints the runtime serves, the REST data API (/api/v1/data/…), the settings, file-download, datasource admin and share-link routes, the marketplace install routes, and the MCP stdio transport.

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

Local stdio transport (opt-in)

Alongside the HTTP endpoint, the runtime can also speak MCP over a long-lived stdio transport — a local pipe for a client on the same host rather than a network surface. It is off by default and deliberately stricter than HTTP; turn it on at boot with two environment variables:

OS_MCP_STDIO_ENABLED=true OS_MCP_STDIO_API_KEY=osk_... os start

The HTTP surface authenticates each caller (OAuth as a person, or their own API key). A stdio pipe has no per-request identity to resolve, so it runs as a single principal you pin up front — the identity of OS_MCP_STDIO_API_KEY. That key is resolved through the same verify + authorization chain as an HTTP/REST request and re-checked on every call, so RBAC, row-level security, field-level security, and tenant isolation apply to the stdio session exactly as they would to that identity in the Console — and revoking the key stops the session on its next call.

The transport is fail-closed: a missing, unknown, revoked, expired, inactive, or owner-less key makes stdio refuse to start rather than fall back to an unscoped or system session — there is deliberately no bypass. For a full-authority local agent, mint the key on a platform-admin or dedicated service identity; for a scoped one, mint it on a user with exactly the access it should have. See environment variables for the switches and ADR-0101 for the decision.

What the agent gets

Twelve tools, generated from your metadata:

The tools are a fixed ~10-tool spine with the object name as a parameter (query_records(objectName, …)), not one tool per object — so the list stays usable on an app with hundreds of objects. Which objects and actions that spine can reach is the default exposure policy (v1):

• 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. In the open framework that means exactly two types — script (with an inline body or a registered handler) and flow (with the automation service registered). url, modal, form, and api have no headless dispatch here. See Actions as Tools and Actions.

Prompts: your skills, served to the client

Tools are not the only primitive. Every skill you author (*.skill.ts, defineSkill) that carries instructions is served as an MCP prompt — so a connected client can list your app's playbooks by name and pull one into the conversation:

export const CaseTriageSkill = defineSkill({
  name: 'case_triage',
  label: 'Case Triage',
  description: 'How this team triages an inbound support case',
  instructions: `Read the case, classify severity from the account tier and the
symptom, then propose the next action. Never close a case the customer has not
confirmed.`,
  tools: ['query_records', 'action_resolve_case'],
});

// prompts/list
{ "prompts": [ { "name": "case_triage", "title": "Case Triage",
                 "description": "How this team triages an inbound support case" } ] }
// prompts/get { "name": "case_triage" } → the instructions text, as a message

In Claude Code that surfaces as /mcp__my-app__case_triage; other clients show prompts in their own picker. Nothing to enable — the surface appears as soon as the app has a skill with instructions, and prompts/list simply returns an empty list until then.

Only the instructions half projects. A skill's tools / surface / triggerConditions are read by the in-product agent runtime (the ask / build agents, cloud / Enterprise), which is the thing that composes a tool set and decides when a skill activates. MCP has neither step: the model lives in your client, driving one flat tool list, and your AI-exposed actions are already reachable there as list_actions / run_action. So on the open framework a skill contributes its judgment (as a prompt), not its wiring — and the same skill file keeps its full meaning when the app runs on the cloud runtime. See AI Agents.

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

Before involving a client, prove the server itself is answering — the anonymous probe below must return 401, which is the surface saying "present, needs a credential" (a WWW-Authenticate header naming the OAuth resource metadata means the browser-login track is live too). Anything else is a server-side issue; see Troubleshooting.

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3000/api/v1/mcp \
  -H 'content-type: application/json' -d '{}'
# → 401

With an API key you can drive the whole protocol from the shell — a handshake, the tool list, and one real read:

MCP=http://localhost:3000/api/v1/mcp
KEY=osk_...
call() { curl -s -X POST "$MCP" -H "x-api-key: $KEY" \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$1"; }

call '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
# → {"result":{"serverInfo":{"name":"objectstack",...},"capabilities":{"tools":{...},"prompts":{}}},...}

call '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | grep -o '"name":"[a-z_]*"'
# → the twelve tools, list_objects … resume_run

call '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_records","arguments":{"objectName":"crm_opportunity","limit":3}}}'
# → {"result":{"content":[{"type":"text","text":"{ \"object\": \"crm_opportunity\", \"records\": [ ... ], \"total\": 23, \"hasMore\": true }"}]}}

Two details that trip up a first attempt: the object argument is objectName, and its value is the object's API name as returned by list_objects (crm_opportunity, not opportunity) — a wrong name comes back as Object 'opportunity' not found.

Then, in the client, 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

• Prompts from your skills — the other MCP primitive this server serves
• 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)
• Connectors — the outbound counterpart: consuming an external MCP server as a flow-dispatchable connector (provider: 'mcp')