LLM Best Practices

How to set up an MCP skill for Claude Code

3 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 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 .claude/settings.json

Claude Code reads MCP server definitions from mcpServers in .claude/settings.json. 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"
    }
  }
}

Secrets belong in .claude/settings.local.json (gitignored), not in the shared settings file.

3. Restart Claude Code and verify tool availability

Claude Code reads mcpServers on startup. Restart the session after editing settings.

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

{
  "allowedTools": [
    "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 allowedTools 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.
  • Secrets appearing in .claude/settings.json: move environment variables with secrets to .claude/settings.local.json and reference them as "${VAR_NAME}" in the shared file.
  • 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.

Graph View

Backlinks