---
title: "How to set up an MCP skill for Claude Code"
slug: "set-up-an-mcp-claude-code-skill"
category: "howto"
tags: ["howto", "mcp", "claude-code", "ai-agents", "tutorial", "skills"]
status: "stable"
last_updated: 2026-08-14
summary: "Register an MCP server as a skill in Claude Code so the agent can call external tools during sessions."
related: ["[[ai-agents/mcp-servers]]", "[[howto/build-an-mcp-server]]", "[[ai-agents/claude-code]]", "[[howto/set-up-claude-code]]", "[[ai-agents/multi-agent]]", "[[tooling/claude-code-workflow]]", "[[howto/run-claude-code-with-mcp]]"]
---

## Overview

An MCP (Model Context Protocol) skill extends Claude Code with external tool access: databases, APIs, file systems, or custom services. This guide registers a local or remote MCP server in Claude Code's settings so the agent can call it during sessions. See [[ai-agents/mcp-servers]] for the protocol background and [[howto/build-an-mcp-server]] for building a server from scratch.

## Prerequisites

- Claude Code installed and authenticated (`claude --version` prints a version).
- An MCP server running locally or reachable over HTTP. The server must implement the MCP protocol and expose a tool list.
- Node 22 or Python 3.11+ depending on the server runtime.
- The server's start command or URL. For `@modelcontextprotocol/server-*` packages, the command is an `npx` invocation.

## Steps

### 1. Identify the server command or URL

Local stdio servers are the most common pattern. The server runs as a child process that communicates over stdin/stdout.

```bash
# Test the server starts without error
npx @modelcontextprotocol/server-filesystem /path/to/allowed/directory
```

SSE (Server-Sent Events) servers are available at an HTTP URL. Confirm the URL responds:

```bash
curl http://localhost:3100/sse
```

### 2. Add the server to `.mcp.json`

Claude Code reads MCP server definitions from `mcpServers` in `.mcp.json` at the project root, not from `.claude/settings.json` (that file holds permissions and hooks). Add an entry for each server.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}
```

For SSE servers, use `url` instead of `command`:

```json
{
  "mcpServers": {
    "my-api": {
      "type": "sse",
      "url": "http://localhost:3100/sse"
    }
  }
}
```

`.mcp.json` is meant to be committed; keep secrets out of it and rely on `${VAR}` environment substitution instead. A teammate who pulls the file sees the server as "Pending approval" in `/mcp` until they run `claude` and accept it.

### 3. Restart Claude Code and verify tool availability

Claude Code reads `.mcp.json` on startup. Restart the session after editing it.

```bash
claude
# In the session:
/mcp
```

The `/mcp` command lists connected servers and their available tools. Each tool appears as a callable function the agent can invoke.

### 4. Authorize tool calls in settings

Claude Code prompts for confirmation on first use of each tool by default. To pre-authorize specific tools and reduce interruptions, add them to `permissions.allow` in `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "mcp__filesystem__read_file",
      "mcp__filesystem__list_directory",
      "mcp__postgres__query"
    ]
  }
}
```

Use the format `mcp__<server-name>__<tool-name>` to match the tool identifier shown by `/mcp`.

### 5. Use the skill in a session

Start a session and reference the tool by name in your brief or let the agent discover it via the tool list.

```
Read the file at /path/to/config.json using the filesystem tool and summarize the settings.
```

Claude Code selects the appropriate MCP tool automatically when the task matches a tool's description.

## Verify it worked

```bash
# Start a session and check MCP status
claude
# Then in session:
/mcp
```

The output should list your server name and its tool count. If the count is greater than zero, the server connected and the tools are available.

## Common errors

- `Server failed to start`: the command in `mcpServers` is wrong or the package is not installed. Run the command manually in a terminal to see the error.
- `Tool not found`: the server connected but the tool name does not match. Run `/mcp` to see exact tool names and update `permissions.allow` accordingly.
- `Permission denied` on stdio server: the command path is not executable or the user lacks permission. Check the path with `which npx` or `ls -la`.
- Server stuck at "Pending approval" in `/mcp`: a fresh clone does not auto-approve its own `.mcp.json`. Run `claude` interactively and accept the workspace trust dialog.
- Secrets appearing in `.mcp.json`: move the literal value out and reference it as `"${VAR_NAME}"`, sourced from an exported shell variable or `.env`.
- Server disconnects during long sessions: stdio servers tied to a process can exit if the parent session resets. Use SSE servers for long-running or remote integrations.

## Related

- [[ai-agents/mcp-servers]]
- [[howto/build-an-mcp-server]]
- [[ai-agents/claude-code]]
- [[howto/set-up-claude-code]]
- [[ai-agents/multi-agent]]
- [[tooling/claude-code-workflow]]
- [[howto/run-claude-code-with-mcp]]