Claude Code MCP servers: setup, config and scoping

Claude Code MCP adds external tools to the terminal coding agent through the Model Context Protocol. It supports local processes and remote servers, with configuration scoped to a project or user. An AIPx agent URL supplies the permitted account tools through a remote HTTP connection authenticated with OAuth.

Add an MCP server to Claude Code

Create an AIPx agent for the repository you are working on, connect the relevant accounts, and copy its MCP URL. Register it from the repository directory:

claude mcp add --transport http --scope project aipx https://dash.aipx.run/mcp/AGENT_ID
claude mcp list
claude mcp get aipx

1. Replace AGENT_ID with the value shown in AIPx.
2. Start Claude Code in the project and run /mcp.
3. Select the AIPx server and authenticate when prompted. Complete the browser OAuth flow.
4. Verify that the expected tools appear.
5. Ask for a known issue or error report before allowing a write.

Use the HTTP transport for AIPx. A local stdio configuration starts a program and exchanges messages through its input and output; it does not describe this hosted endpoint. Anthropic’s MCP reference documents the command syntax, authentication and diagnostics. The older SSE transport is deprecated where HTTP is available.

Do not put a provider token into this command. Connecting Claude Code to AIPx and connecting AIPx to an upstream service are different authentication steps.

Claude Code MCP config: .mcp.json and scopes

Project-scoped registration produces a .mcp.json entry. A remote entry needs its transport type as well as the URL:

{
  "mcpServers": {
    "aipx": {
      "type": "http",
      "url": "https://dash.aipx.run/mcp/AGENT_ID"
    }
  }
}

Scope decides where the configuration applies. Local scope is the default for the add command and is associated with the current project in your personal configuration. Project scope uses .mcp.json, which can be shared with collaborators. User scope applies across projects. Local and user registrations live in ~/.claude.json; they are not the same as a checked-in project file.

Scope	Choose it when	Review before sharing
Local	Testing one repository personally	The current working directory
Project	The repository should declare its connection	Endpoint ownership and intended agent
User	You use a connection across repositories	Whether broad availability fits your workflow

A shared endpoint declaration does not share OAuth credentials. Every user still needs the appropriate authorization. For a personal AIPx agent, keep the declaration local unless collaborators should use that endpoint too. Before trusting repository configuration, inspect every command and URL it contains.

Best MCP servers for Claude Code

The most useful additions supply context missing from the checkout. Filesystem and shell access already exist in the coding client; another server is useful when it adds a specific boundary or capability, rather than repeating those tools.

Server or integration	Coding task	Recommended starting rule
GitHub	Read linked issues and review context	Allow relevant reads; Confirm writes
Linear	Retrieve the implementation brief	Confirm issue changes
Sentry	Investigate a production stack trace	Allow selected project reads
PostHog	Check evidence about a feature’s usage	Limit analytics access to the project
Jira	Load acceptance criteria	Hide unrelated account tools
Confluence	Find architectural decisions	Restrict the upstream spaces
Supabase	Inspect database context	Prefer project-scoped read-only access
Cloudflare	Research infrastructure state	Review operations before enabling writes
Notion	Read planning documents	Confirm document edits
Google Sheets	Read a rollout checklist	Confirm cell updates
Stripe	Research a billing integration	Keep financial changes on Confirm
Gmail	Retrieve an explicitly needed discussion	Hide personal mail from coding agents

These are task choices, rather than a claim that every project needs twelve servers. The best MCP servers guide compares deployment, authentication and cost. Begin with your issue tracker and error tracker if that is where the missing information lives.

Claude Code tools vs MCP servers

Built-in tools work with the repository and local execution environment. MCP tools reach a separate process or service. A prompt such as “fix the error attached to this issue” may use a tracker to obtain the brief, Sentry to obtain the stack trace, and the coding client’s existing tools to edit and test the code.

A successful external call does not validate the code change. Keep repository checks in the workflow. Likewise, a local permission to run a shell command does not authorize an upstream tool call: those are different capabilities. If you alternate between terminal and editor workflows, compare Cursor MCP setup and Codex MCP setup. Their files and commands are different even when the server URL is identical.

Give Claude Code only the tools it needs

Create one AIPx agent per project when the projects need different access. Give the billing project access to the billing account, while a documentation project gets only the relevant documents and tracker. This keeps tools available to the model aligned with the task.

AIPx rules combine tool, account and agent. Keep ordinary relevant reads on Allow, writes on Confirm, and unrelated or destructive operations on Hide. The defaults treat ordinary read-only tools as Allow and other operations as Confirm, with integration-specific exceptions such as AgentMail. Defaults are a starting point; inspect them before connecting confidential accounts.

AIPx communicates Confirm through tool metadata; the client decides how to handle approval. Do not assume every MCP client blocks a direct call until a person approves it. For a strict unavailable-operation boundary, use Hide. Review the account and arguments in any client confirmation, especially when similarly named accounts are connected. Use the audit record to verify the tool’s result after execution. The MCP gateway explanation covers the account connection model, and remote MCP servers covers its deployment boundary.

Troubleshooting Claude Code MCP

The server is registered but unavailable. Check claude mcp get aipx for the URL and type. A URL without "type": "http" in JSON can be treated as a stdio declaration. Check that you launched the client in the intended repository and that the registration scope covers it.

Authentication fails. Open /mcp and inspect the server’s authentication state. Repeat OAuth when credentials are expired or revoked. An upstream provider authorization failure requires reconnecting that provider account in AIPx, rather than replacing the client URL.

A tool is missing. Look for Hide rules, the wrong account assignment, or stale tool discovery. Refresh the connection after changing its configuration. Broadening every permission makes diagnosis harder and can expose unnecessary tools.

A local server will not start. This is a separate class of problem: verify its command exists and is available in the client’s environment. A working terminal PATH does not prove another host process can find the executable.

A direct official server can be simpler for one vendor, and a local server is appropriate for private files. AIPx adds a hosted operator and a network dependency in exchange for a shared account and permission layer.

Connect your tools to Claude Code

The services already linked in the development table cover common coding context. Other supported connections below fit infrastructure, billing or explicitly authorized personal tasks; do not add them all to a repository agent.

• Development and infrastructure: Atlassian Rovo tools, DigitalOcean infrastructure.
• Mail, notes and planning: Google Calendar events, Apple Calendar access, Things 3 tasks, Granola meeting notes, Fireflies transcripts, AgentMail inbox tools.
• Payments: Paddle subscription tools.
• Research and campaign data: Exa web search, Google Maps data, X account tools, Yandex Direct campaigns.
• Personal health and nutrition: WHOOP recovery data, Withings measurements, Hevy workouts, Numon nutrition reports.

Choose one repository, one agent and a small set of verifiable read tasks. Free supports three connected accounts and one agent; Pro costs $3 per month for unlimited accounts and agents plus Pro integrations. Connect free. For Claude’s browser connector interface, use the separate Claude MCP guide.