How to use an MCP server in Claude Code

To use an MCP server in Claude Code: generate the server from your OpenAPI spec, then either run claude mcp add to register it or check a .mcp.json file into your project root so the whole team gets the same servers. Both paths end at the same place — Claude Code connects to the server and gains every tool it exposes. This post covers the generate-then-wire flow, verified against Claude Code's own docs.

Step 1: generate the MCP server from your spec

Claude Code, like Cursor and Gemini CLI, doesn't read an OpenAPI spec itself — it reads an MCP server. Sourced's OpenAPI-to-MCP workflow takes one spec and produces a reviewed tool surface, a safety report, install snippets, and either a managed remote endpoint or a downloadable TypeScript server. Review the tool names, descriptions, and destructive classifications before you register anything — that review is the actual security control, not the config step that follows.

For the shortest remote path, select Host with Sourced after the review. Copy the hosted URL and the one-time endpoint token into the HTTP command below. Keep the upstream API credential in Sourced; do not put it in Claude Code's config.

Step 2: register it with Claude Code

Option A — the claude mcp add CLI

# Local stdio server (the common case right after building the generated package)
claude mcp add --transport stdio your-api \
  --env YOUR_API_API_KEY=your-key-here \
  -- node /absolute/path/to/dist/index.js

# Remote HTTP server, if you've deployed the generated server behind HTTPS
claude mcp add --transport http your-api https://mcp.your-api.example.com/mcp \
  --header "Authorization: Bearer your-token-here"

The --scope flag controls where the registration lives:

Scope	Stored in	Visible to
local (default)	~/.claude.json	Just you, just this project
project	.mcp.json in the repo root	Your whole team, once committed
user	~/.claude.json	Just you, every project

Use claude mcp add --scope project your-api ... when you want the server checked into the repo so every teammate who clones it gets the same config.

Option B — a project .mcp.json file directly

{
  "mcpServers": {
    "your-api": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "YOUR_API_API_KEY": "${YOUR_API_API_KEY}"
      }
    }
  }
}

Or for the remote/hosted case:

{
  "mcpServers": {
    "your-api": {
      "type": "http",
      "url": "https://mcp.your-api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${YOUR_API_TOKEN}"
      }
    }
  }
}

.mcp.json at the project root is checked into git and shared with the team; teammates still authenticate individually (their own API key or OAuth token) even though the server definition is shared. Claude Code prompts for approval before using a project .mcp.json server the first time in an interactive session — that choice is stored locally per project, and non-interactive runs (claude -p, the Agent SDK, cloud sessions) load configured servers without prompting, so keep your default tool set conservative if you expect non-interactive use.

What Claude Code can then do

Once registered, Claude Code lists your API's operations as tools alongside its built-in file, search, and shell tools, and can call them as part of planning a task — "check whether this customer's last invoice is paid" becomes a tool call if your spec has the matching read operation, with no glue code from you. As with any MCP client, write and destructive operations should be excluded from the default set or require explicit confirmation; that's a property of how the server was generated, covered in the MCP security checklist.

Review before you enable it

• Confirm destructive tools (delete, refund, revoke, send, publish) are excluded from the default set, or tagged so Claude Code's confirmation behavior applies.
• Keep credentials in environment variables, referenced via ${VAR} in .mcp.json, never as literal values in a file that gets committed.
• If the server needs OAuth, Claude Code supports oauth.clientId, oauth.callbackPort, and oauth.scopes in the server entry — don't roll your own token flow inside the generated code.
• Run claude mcp list after adding a server to confirm it's actually connected before relying on it in a real task.

Honest scope: when a plain API call beats MCP in Claude Code

If you need Claude Code to hit an endpoint once while debugging, a curl command it runs through its shell tool is faster than generating and registering an MCP server for a one-off. MCP is worth the setup when the same tool surface needs to be available across many sessions, when it should also work unchanged in Cursor, Copilot, or Gemini CLI, or when you want a reviewed, narrow tool set that teammates reuse without re-deriving it from your API docs each time. See the OpenAPI-to-MCP server post for what maps cleanly from a spec versus what still needs a human pass.

FAQ

How do I add an MCP server to Claude Code?

Either run claude mcp add with --transport stdio (local) or --transport http (remote), or write a .mcp.json file at your project root with a mcpServers object. Both register the same kind of server; .mcp.json is the one that's naturally shared via git.

What's the difference between local, project, and user scope?

local (the default) is stored in ~/.claude.json and applies only to you in the current project. project writes to a .mcp.json file in the repo root, shared with your team via source control. user is stored in ~/.claude.json but applies across every project you open.

Does Claude Code support remote MCP servers, not just local ones?

Yes. Use --transport http with claude mcp add, or a "type": "http" entry in .mcp.json with a url and optional headers for auth. SSE is also supported but Anthropic's docs mark it deprecated in favor of HTTP.

Is it safe to commit a project .mcp.json to a public repo?

Only if it has no literal secrets. Use ${VAR} environment-variable expansion for API keys and tokens in command, args, env, url, and headers so the committed file references credentials rather than containing them.

Can I generate a Claude Code-ready MCP server from my OpenAPI spec?

Yes. Sourced's OpenAPI-to-MCP workflow produces a TypeScript MCP server or a managed remote endpoint plus install snippets for Claude Code and several other hosts, with a safety report you review before registering it.

Does Claude Code ask for approval before using a project's MCP servers?

In interactive sessions, yes — the first use of a project .mcp.json server prompts for approval, and that choice is remembered per project. Non-interactive runs (scripted, CI, or Agent SDK sessions) load configured servers without prompting, so review your default tool set with that in mind.

Ready to try it. Generate and host an MCP server from your OpenAPI spec, or compare the managed and self-hosted paths in the MCP server hosting guide.