ClaudeDetails
UpdatesGuidesModelsMCPToolsLearning PathsFAQ
UpdatesGuidesModelsMCPToolsLearning PathsFAQ

On this page

What MCP does for Claude CodeFinding and building serversOption 1: Remote HTTP servers (recommended for remote)Option 2: Remote SSE servers (deprecated)Option 3: Local stdio serversWhere to go nextFAQ
Home/Guides/Claude Code
Claude CodeINTERMEDIATE

Connecting Claude Code to External Tools with MCP: Servers, Transports, and Configuration

Needs reviewLast verified August 12, 2026·5 min read

This guide explains how to connect Claude Code to external tools and data sources using the Model Context Protocol (MCP). It covers what MCP connections enable, such as working with issue trackers, databases, and monitoring tools; where to find reviewed connectors; how to scaffold your own server with the official mcp-server-dev plugin; and how to install remote HTTP, remote SSE, and local stdio servers, including transport-specific flags, JSON configuration pitfalls, and environment variables like CLAUDE_PROJECT_DIR.

What MCP does for Claude Code

Claude Code can connect to hundreds of external tools and data sources through the Model Context Protocol (MCP), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.

The practical signal for when to connect a server: you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard. Once connected, Claude can read and act on that system directly instead of working from what you paste.

With servers connected, Anthropic's documentation lists example requests such as:

  • "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."
  • "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."
  • "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."
  • "Update our standard email template based on the new Figma designs that were posted in Slack"
  • "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."

An MCP server can also act as a channel that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you're away.

Finding and building servers

Reviewed connectors are listed in the Anthropic Directory. Directory connectors use the same MCP infrastructure as Claude Code, so any remote server listed there can be added with claude mcp add.

One caution from the docs is worth repeating: verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk.

To build your own server, the docs point to the MCP server guide for protocol fundamentals and the Claude connector building docs for authentication, testing, and Directory submission. You can also have Claude scaffold a server for you with the official mcp-server-dev plugin:

code
/plugin install mcp-server-dev@claude-plugins-official

If the install fails, match the reported message:

  • Marketplace "claude-plugins-official" not found: add the marketplace with /plugin marketplace add anthropics/claude-plugins-official, then retry.
  • Plugin not found in the marketplace: check the plugin name. Claude Code refreshes a stale marketplace catalog and retries before reporting this, so if you turned off marketplace auto-update, refresh manually with /plugin marketplace update claude-plugins-official and retry.

If the install summary reports Run /reload-plugins to activate., run that command. Then run the build skill:

code
/mcp-server-dev:build-mcp-server

Claude asks about your use case and scaffolds a remote HTTP or local stdio server.

Option 1: Remote HTTP servers (recommended for remote)

HTTP is the recommended transport for remote MCP servers and the most widely supported for cloud-based services.

bash
# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

When configuring servers via JSON in .mcp.json, ~/.claude.json, or claude mcp add-json, the type field accepts streamable-http as an alias for http. The MCP specification uses streamable-http for this transport, so configurations copied from server documentation work without modification.

One configuration error to avoid: a JSON entry with a url but no type. Claude Code reads an entry with no type as a stdio server, so it skips the server and reports MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Before v2.1.202, this misconfiguration was reported as command: expected string, received undefined.

In --output-format stream-json runs, Claude Code also reports a skipped --mcp-config entry in the system/init event's mcp_server_errors field, so scripts can detect that the server never loaded. This requires Claude Code v2.1.219 or later.

Option 2: Remote SSE servers (deprecated)

The SSE (Server-Sent Events) transport is deprecated; use HTTP servers instead where available. Some services still expose only an SSE endpoint. Use the same command shape with --transport sse:

bash
# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3: Local stdio servers

Stdio servers run as local processes on your machine. They're suited to tools that need direct system access or custom scripts.

bash
# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

CLAUDE_PROJECT_DIR

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment to the project root, so your server can resolve project-relative paths without depending on the working directory. This is the same directory hooks receive in their CLAUDE_PROJECT_DIR variable. Read it from inside your server process — for example, process.env.CLAUDE_PROJECT_DIR in Node or os.environ["CLAUDE_PROJECT_DIR"] in Python.

CLAUDE_PROJECT_DIR is the stable project root and doesn't change when you add or remove working directories mid-session. A server that limits its own filesystem access to a set of allowed directories should implement the MCP roots/list request instead. Claude Code answers roots/list with the session's launch directory plus every additional working directory you've granted with --add-dir, /add-dir, or the additionalDirectories setting, and sends notifications/roots/list_changed when that set changes. Before v2.1.203, roots/list returned only the launch directory and no change notifications were sent.

Note a subtlety about variable expansion: CLAUDE_PROJECT_DIR is set in the server's environment, not in Claude Code's own environment. Referencing it via ${VAR} expansion in the command or args of a project-scoped .mcp.json entry, or a local- or user-scoped server entry in ~/.claude.json, requires a default such as ${CLAUDE_PROJECT_DIR:-.}. Plugin-provided MCP configurations substitute ${CLAUDE_PROJECT_DIR} directly and don't need the default.

Where to go next

If this is your first server, Anthropic's docs recommend the MCP quickstart for a step-by-step walkthrough; the page summarized here is the full reference.

This guide is based on Anthropic's Claude Code documentation and is not an official Anthropic publication.

claudedetails.com is an independent publication and is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic, PBC, used here for identification purposes only. Product details can change — always confirm specifics on Anthropic's own site before making decisions based on this post.

FAQ

Why does Claude Code say my MCP server has a "url" but no "type"?

A JSON entry with a url but no type is a configuration error: Claude Code reads an entry with no type as a stdio server, skips it, and reports the error telling you to add "type": "http" (or "sse" / "ws"). Before v2.1.202, the same misconfiguration was reported as `command: expected string, received undefined`.

Should I use HTTP or SSE transport for remote MCP servers in Claude Code?

Use HTTP where available — it's the recommended option and the most widely supported transport for cloud-based services. SSE is deprecated, but some services still expose only an SSE endpoint; for those, use the same claude mcp add command with --transport sse.

Can I use "streamable-http" as the type in my .mcp.json?

Yes. When configuring servers via JSON in .mcp.json, ~/.claude.json, or claude mcp add-json, the type field accepts streamable-http as an alias for http. The MCP specification uses that name, so configurations copied from server documentation work without modification.

How does an MCP stdio server find the project root in Claude Code?

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server's environment to the project root — read it from inside the server process, e.g. process.env.CLAUDE_PROJECT_DIR in Node or os.environ["CLAUDE_PROJECT_DIR"] in Python. It's stable and doesn't change mid-session; servers that need the current set of allowed directories should implement the MCP roots/list request instead.

More in Claude Code

Claude CodeBEGINNER
Aug 12, 2026

Common Claude Code Workflows: Exploring Code, Fixing Bugs, Testing, and PRs

This guide walks through the everyday prompt patterns Anthropic documents for Claude Code: getting an overview of an unfamiliar codebase, locating relevant files, fixing bugs from error messages, refactoring legacy code safely, adding tests for uncovered code, creating pull requests, and generating documentation. It also notes related workflows the docs cover, such as resuming sessions, running parallel sessions with worktrees, planning before edits, delegating research to subagents, and piping Claude into scripts.

Read guide →
Claude CodeINTERMEDIATE
Aug 11, 2026

Using Claude Code on a React Project: CLAUDE.md, Permissions, and Workflow Tips

Claude Code has no React-specific mode — what actually makes it effective on a React codebase is the same CLAUDE.md and permissions setup that works on any project, applied deliberately. This guide walks through what to put in CLAUDE.md for a React app, which commands to allow, and how to structure a component or test-fixing session.

Read guide →
Claude CodeBEGINNER
Aug 11, 2026

How to Create Your First Claude Code Plugin: Manifest, Skills, and Local Testing

This guide explains how to create a custom Claude Code plugin from scratch. It covers when to use a plugin versus standalone configuration in the .claude directory, how to structure a plugin directory with a .claude-plugin/plugin.json manifest, how to add a skill using a SKILL.md file, how to test the plugin locally with the --plugin-dir flag, and how to make skills accept user input with the $ARGUMENTS placeholder. It is based on Anthropic's documentation for Claude Code plugins.

Read guide →
ClaudeDetails
UpdatesGuidesModelsMCPToolsLearning PathsFAQRSS
Get new guides and Claude updates by email

Occasional, no spam. Unsubscribe anytime.

claudedetails.com is an independent publication and is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic, PBC, used here for identification purposes only. Product details can change — always confirm specifics on Anthropic's own site before making decisions based on this post.