Connect Cursor and Claude Code to your internal API over MCP (step by step)

The first week of using a coding agent against your company's API is always the same: paste the docs URL into the prompt, correct the base path, correct the auth header, correct the pagination type, correct the envelope wrapper, repeat in every new session and every new tool. Agents change by the month — Cursor, Claude Code, whatever comes next — but the integration work keeps being redone. The Model Context Protocol exists to make the API discoverable once. This walks through connecting a real internal API to both Cursor and Claude Code over MCP, with the credential scoping and verification steps that tutorials skip.

What you need before starting

• An OpenAPI document for the API, 3.1 or 3.2 preferred. It does not need to be perfect, but operationIds should be unique and verb-first, request bodies should have schemas, and enums must be actual enums — agents choose from them.
• A way to serve it as MCP: a local server launched from the spec file, or a hosted MCP endpoint with tokens.
• A sandbox target. The agent's first week should never point at production write operations. A staging server, a sandbox organization, or a spec-driven mock is the right first peer.
• Scoped credentials: a token for the agent, not your personal admin token.

Step 1: serve the spec locally

A local MCP server reads the spec file and exposes operations as tools over stdio, which is how desktop agent clients spawn local capabilities:

{
  "mcpServers": {
    "billing-api": {
      "command": "npx",
      "args": [
        "@powerduck/openapi-to-mcp-server",
        "--spec",
        "/Users/me/work/api-specs/billing.openapi.yaml"
      ],
      "env": {
        "PD_API_TOKEN": "scoped-staging-token",
        "PD_API_BASE_URL": "https://staging.api.example.com"
      }
    }
  }
}

The token lives in the server process environment, never in the spec, the prompt, or committed code. If the spec documents multiple servers, pin the base URL explicitly so the agent cannot drift into production because staging was listed second.

For teams that do not want every developer running a local process, the hosted equivalent is an HTTPS MCP endpoint authenticated with a per-user or per-integration token; the client configuration then carries the URL and an Authorization header instead of a spawned command.

Step 2: register it in Cursor

Cursor reads MCP configuration from its settings UI or the project-level .cursor/mcp.json (project-level is the right choice for internal APIs, because it travels with the repository):

{
  "mcpServers": {
    "billing-api": {
      "command": "npx",
      "args": ["@powerduck/openapi-to-mcp-server", "--spec", "./api-specs/billing.openapi.yaml"],
      "env": {
        "PD_API_TOKEN": "${BILLING_API_TOKEN}",
        "PD_API_BASE_URL": "https://staging.api.example.com"
      }
    }
  }
}

Environment variable expansion keeps secrets out of git. After saving, Cursor's MCP panel should list the billing tools — one per exposed operation. Verify the count matches the operation set you intended to expose (see step 5 on filtering).

Step 3: register it in Claude Code

Claude Code configures MCP servers through its CLI/config flow, producing the same logical entry:

claude mcp add billing-api \
  --env BILLING_API_TOKEN \
  --env PD_API_BASE_URL=https://staging.api.example.com \
  -- npx @powerduck/openapi-to-mcp-server --spec /Users/me/work/api-specs/billing.openapi.yaml

For a hosted endpoint, add an HTTP-type server with the endpoint URL and the bearer token; the agent then connects over streamable HTTP instead of spawning a process. Scope the config to the project directory (--scope project) so the tools only appear when working in this codebase — global registration of every internal API produces a tool list so large that selection quality degrades.

Step 4: verify the connection like an engineer

Do not trust "tools appeared." Run through this checklist in both clients:

1. Discovery: tool count equals the exposed operation count; names are the operationIds; descriptions are present.
2. A read call: ask the agent to list resources; confirm the request hits staging with the right headers and returns parsed data.
3. A validation failure: ask it to call a tool with a deliberately wrong type (a string where an integer is required). The MCP server must reject the call pre-flight with a schema error. If the request reaches the API and returns a 422, validation is not wired.
4. Auth failure: remove the token and confirm a clean, readable auth error rather than a hang or an HTML login page.
5. A write call: perform one create against the sandbox and confirm the body arrived with the documented content type and the agent can read back the created resource.
6. Streaming (if applicable): exercise one SSE tool and confirm it returns collected events rather than timing out.
7. No credential leakage: ask the agent to print its configuration; the token must never surface in chat or generated code.

Step 5: expose the right surface

Agents handle a focused tool catalog far better than a 300-operation firehose. Three practices keep selection accurate:

• Filter by audience. Expose a tagged subset for agent use — read operations plus a controlled set of writes — and keep destructive or admin operations off the agent server entirely.
• Name tools for what they do. list_invoices, create_subscription, cancel_subscription; not getAll, postData.
• Write descriptions that say when. "Cancels a subscription at period end; use instead of deleting" guides selection in ways the path alone cannot. Errors should carry stable machine codes (problem+json type values) so the agent can self-correct without asking.

Step 6: decide local vs hosted

Most teams start local (it takes ten minutes and one spec file) and add the hosted endpoint when onboarding the fifth developer or an external integration. Both should serve the same document revision so behavior does not diverge between them.

Operating notes

• Version the tools. Pin the agent servers to a released spec revision; breaking tool names or arguments breaks saved agent workflows the same way it breaks SDKs. Run the breaking-change diff before publishing a new revision.
• Audit calls. Log which agent (user, project) called which tool; agents make mistakes at machine speed and the call log is the debugging trail.
• Keep humans on destructive actions. Deletes, plan changes, and payments should require confirmation in the client or be absent from the agent catalog entirely.
• Docs stay for humans. MCP tools assume you already know the domain; new team members still learn concepts from the rendered documentation. Both derive from the same spec.

With this setup, switching agents is a configuration change rather than an integration project — the API knowledge lives in the contract, not in prompt history. Powerduck serves the local MCP endpoint from the spec open in the workspace and publishes hosted, token-scoped endpoints with versioning from Cloud; the demo shows the serve action on a sample document.

What to read next: MCP vs function calling vs plugins clarifies the layers, and stop pasting API docs into AI coding agents covers why prose context decays while typed tools do not.