# Claude Code MCP tool integration

> Claude Code: HTTP, SSE, stdio, and WebSocket MCP connections, scopes, trust, OAuth, and tool search.

URL: https://docs.passion8.cc/en/docs/claude-code/mcp
Language: en
Publisher: Passion8

MCP connects Claude Code to external tools and data, including browsers, databases, project-management systems, design tools, and internal APIs.




MCP servers bring external content into context and may perform real operations. Connect only trusted servers and use permissions and hooks for writes.




## Connection methods

| Transport | Recommendation | Use case | Command |
| --- | --- | --- | --- |
| HTTP | Recommended | Remote SaaS and hosted MCP | `claude mcp add --transport http` |
| SSE | Legacy | Older MCP services | `claude mcp add --transport sse` |
| stdio | Recommended | Local scripts, databases, and browsers | `claude mcp add <name> -- <command>` |
| WebSocket | Specialized | Remote servers that push events | `claude mcp add-json` |

### HTTP

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
```

The configuration `type` can be `http` or `streamable-http`.

### SSE

```bash
claude mcp add --transport sse asana https://mcp.asana.com/sse
```

SSE is a legacy transport. Prefer HTTP for new services.

### Local stdio

```bash
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server
```

The `--` separator matters: it separates Claude Code arguments from the server command.

Claude Code injects `CLAUDE_PROJECT_DIR` into stdio servers so they can find the project root.

### WebSocket

```bash
claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
```

WebSocket suits servers that push events. HTTP is simpler for ordinary request/response tools.

## Scopes

| Scope | Available in | Shared? | Storage |
| --- | --- | --- | --- |
| local | Current project | No | Project entry in `~/.claude.json` |
| project | Current project | Yes | Project-root `.mcp.json` |
| user | All projects | No | `~/.claude.json` |

```bash
# Default local scope: current project only
claude mcp add --transport http stripe https://mcp.stripe.com

# Project scope: writes a shareable .mcp.json
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# User scope: available across projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
```

Project `.mcp.json` triggers a trust confirmation. A cloned repository cannot approve its own servers through committed settings; the user must confirm interactively.

## Management commands

| Command | Purpose |
| --- | --- |
| `claude mcp list` | List servers, connection states, and pending approvals |
| `claude mcp get <name>` | Inspect one server |
| `claude mcp remove <name>` | Remove a server |
| `claude mcp login <name>` | Complete OAuth login |
| `claude mcp logout <name>` | Clear OAuth credentials |
| `/mcp` | Inspect status, authorization, and diagnostics in-session |

HTTP/SSE connections reconnect after disconnection. A terminated local stdio process does not automatically restart.

## Tool names and permissions

MCP names have this shape:

```text
mcp__<server>__<tool>
```

Example:

```json title=".claude/settings.json"
{
  "permissions": {
    "allow": [
      "mcp__github__get_*"
    ],
    "ask": [
      "mcp__database__write_*"
    ],
    "deny": [
      "mcp__dangerous__*"
    ]
  }
}
```

Use the full prefix when matching MCP tools in hooks:

```json title=".claude/settings.json"
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [{ "type": "command", "command": "./.claude/hooks/audit-mcp.sh" }]
      }
    ]
  }
}
```

## Tool search and caching

Claude Code can defer MCP definitions to reduce prompt size and cache invalidation when tools change.

With a custom `ANTHROPIC_BASE_URL`, defaults are more conservative: tool search may be disabled for a non-first-party gateway. Enabling it on Passion8 depends on forwarding `tool_reference` and related request fields.

| Variable | Effect |
| --- | --- |
| `ENABLE_TOOL_SEARCH=true` | Force an attempt to defer tools |
| `ENABLE_TOOL_SEARCH=auto` | Load small tool sets upfront and defer larger sets |
| `ENABLE_TOOL_SEARCH=false` | Put all definitions in the prefix |




If enabling tool search causes requests to fail, the provider or gateway may not support the required fields. Set `ENABLE_TOOL_SEARCH=false` while investigating passthrough support.




## Output and timeouts

| Variable | Purpose |
| --- | --- |
| `MCP_TIMEOUT` | Server startup/connection timeout |
| `MCP_TOOL_TIMEOUT` | Tool execution timeout |
| `MAX_MCP_OUTPUT_TOKENS` | Tool output token limit |
| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | Remote-tool idle timeout |

Database, browser, and log tools can return large results. Prefer pagination and filtering over simply increasing the output limit.

## Official references

- [Connect Claude Code to tools via MCP](https://code.claude.com/en/docs/en/mcp.md)
- [MCP quickstart](https://code.claude.com/en/docs/en/mcp-quickstart.md)
- [Prompt caching and MCP tool changes](https://code.claude.com/en/docs/en/prompt-caching.md)