LLM Best Practices

How to set up an MCP skill for Claude Code

4 min read

View markdown source

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 mcp-servers for the protocol background and 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.

# 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:

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.

{
  "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:

{
  "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.

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:

{
  "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

# 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.

Backlinks