Connecting Your First MCP Server

MCP (Model Context Protocol) lets your agent CLI talk directly to databases, filesystems, and APIs - no copy-paste required. Here is how to wire one up, what breaks, and what to watch.

TL;DR: MCP (Model Context Protocol) is an open standard that lets any AI agent CLI connect to real external systems - your local filesystem, a SQLite database, a REST API. Once connected, you stop pasting data into chat and just ask for what you need. This guide walks you through adding your first server in under ten minutes, then explains the gotchas that catch most people on the first try.

What MCP Actually Does (and Why You Care)

Before MCP, connecting an AI agent to an external tool meant writing custom glue code for every combination of agent and tool. The Model Context Protocol fixes that with a single open standard, built on JSON-RPC 2.0, that any client and any server can speak.

The architecture has three parts:

Host - the AI application you run (Claude Code, Claude Desktop, VS Code Copilot, Cursor). It manages connections and coordinates everything.
Client - a connection object the host creates, one per server.
Server - a separate process (local or remote) that exposes tools, resources, and prompts your agent can use.

Think of it like a USB-C port. The protocol is the port shape. Any server that speaks MCP plugs straight in - you do not rewrite anything per-tool.

Servers expose three kinds of things:

Tools - executable functions the agent invokes (run a SQL query, write a file, call an API endpoint).
Resources - data the agent can read as context (a file's contents, a database schema, an API response).
Prompts - reusable templates for structuring interactions with the LLM.

The result: instead of copying rows out of a database and pasting them into your chat window, you ask Claude to "find the ten users who signed up last week" and it queries the database directly.

Before You Start: Two Transport Options

MCP servers communicate over one of two standard transports. Picking the wrong one wastes time, so choose upfront.

stdio (standard input/output) - the server runs as a local subprocess on your machine. Claude Code spawns it, talks to it over stdin/stdout, and kills it when the session ends. This is the right choice for local tools: a filesystem server, a SQLite file, a local script.
Streamable HTTP - the server runs somewhere (your machine or a remote host) and Claude talks to it over HTTP POST, optionally with Server-Sent Events for streaming. Use this for cloud services, shared team tools, and anything that needs OAuth. The older HTTP+SSE-only transport from MCP spec 2024-11-05 is deprecated - use Streamable HTTP instead.

Your First Server: the Filesystem

The official filesystem server is the fastest way to see MCP working. It gives Claude secure, scoped access to directories you specify - nothing outside those paths is reachable.

Step 1 - Add the server with one command

In Claude Code, run:

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

Replace /Users/you/projects with the directory you want to expose. You can list multiple paths separated by spaces. The -- double-dash is required - everything after it is passed to the server process itself, not to Claude Code.

Claude Code stores this in ~/.claude.json under your current project path (local scope, private to you). To share it with your whole team, add --scope project and it goes into .mcp.json at the repo root instead.

Step 2 - Verify it connected

Inside a Claude Code session, run:

/mcp

You should see filesystem listed with a tool count next to it. If the count is zero or the server shows as failed, skip to the troubleshooting section below.

Step 3 - Use it

Ask Claude something like:

List all TypeScript files in my projects folder, then show me the largest one.

Claude calls the filesystem server's tools directly. No copy-paste. No manual file reading. The agent does it.

Connecting a Real Database (SQLite)

The filesystem is a warm-up. Connecting a database is where MCP starts paying off fast.

The official SQLite reference server was archived (Anthropic now actively maintains seven reference servers: Everything, Fetch, Filesystem, Git, Memory, Sequential Thinking, and Time). For SQLite, community servers fill the gap cleanly. One well-maintained option is the mcp-sqlite package on npm:

claude mcp add --transport stdio my-db -- npx -y mcp-sqlite /absolute/path/to/your.db

Once connected, you can ask things like:

"Show me the schema for all tables."
"Find every user who signed up in the last 30 days."
"Count records by status and sort descending."

The server handles read and write operations - so be specific about what you want, and review what Claude proposes before it runs a destructive query.

Passing secrets safely

For servers that need credentials (a database password, an API key), use --env to pass them at connection time:

claude mcp add --env DB_PASSWORD=yourpassword --transport stdio pg-server -- npx -y @your-org/pg-mcp-server

Claude Code stores the env value in ~/.claude.json (local scope) - it does not go into .mcp.json, so team-shared configs never contain secrets. If you use project scope, use a placeholder and document that teammates need to supply the real value locally.

Connecting a Remote HTTP Server

Remote servers are even simpler to add because you skip the -- separator entirely:

claude mcp add --transport http notion https://mcp.notion.com/mcp

If the server needs a token:

claude mcp add --transport http my-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token-here"

For servers that use OAuth (most major SaaS integrations), add the server first, then run /mcp inside Claude Code and select "Authenticate" next to the server name. Claude Code handles the OAuth flow in your browser and stores the token securely.

Remote HTTP and SSE servers that drop mid-session reconnect automatically with exponential backoff - up to five attempts, starting at a one-second delay and doubling each time. You can watch the reconnection state in /mcp.

What the Config File Actually Looks Like

If you prefer editing JSON directly instead of using the CLI, the structure is the same whether it lives in ~/.claude.json or .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

One important note: Claude Code never reads claude_desktop_config.json - that is Claude Desktop's file. They are different apps with separate config files. If you have servers set up in Claude Desktop and want them in Claude Code too, run:

claude mcp add-from-claude-desktop

That opens an interactive dialog where you select which servers to import. Note: this command only works on macOS and Windows Subsystem for Linux (WSL).

What Breaks and How to Fix It

These are the four failure modes that trip up almost everyone on the first connection.

Server shows as "failed" in /mcp

First check: run the server command manually in your terminal and see what it prints to stderr.

npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

If it crashes immediately, the problem is almost always one of these:

Node.js not installed, or wrong version.
The path argument is relative, not absolute. MCP servers require absolute paths.
A missing dependency or permission error on the binary.

Server connects but tools do not show up

Run /mcp inside Claude Code and look at the tool count. A count of zero next to a connected server usually means the server started but advertised no tools (perhaps because a path it needs does not exist, or an API key it needs is missing). Check the server's own docs for required arguments.

Permission prompt keeps firing

By default, Claude Code asks for confirmation before running any MCP tool call. You can allow specific tools permanently in .claude/settings.json under the permissions key. Only do this for tools you fully trust - a filesystem write tool with blanket permission is a footgun.

Output truncated or tool call times out

Claude Code shows a warning when a tool returns more than 10,000 tokens of output. If you hit that regularly, set MAX_MCP_OUTPUT_TOKENS in your environment before launching Claude Code:

MAX_MCP_OUTPUT_TOKENS=50000 claude

For slow tools (a heavy database query, a long-running script), add a timeout field in milliseconds to that server's config entry in .mcp.json. The default wall-clock limit is generous but not infinite.

Scopes: Personal vs. Team vs. Everywhere

Claude Code has three scopes for MCP configs. Pick the right one from the start or you will spend time wondering why a teammate cannot see your server.

Local (default) - stored in ~/.claude.json, tied to the current project, visible only to you. Right for personal dev servers and anything with credentials.
Project - stored in .mcp.json at the repo root, committed to version control, shared with the whole team. Right for shared tools like a team database server or a company API. Never put real secrets here.
User - stored in ~/.claude.json globally, loads in every project you open. Right for servers you want everywhere - a personal memory server, a time/timezone tool, a productivity API.

When a project-scoped server appears for the first time, Claude Code marks it as "pending approval" until you explicitly approve it in /mcp. That approval step is intentional - it prevents a malicious .mcp.json committed by someone else from silently running code on your machine.

Key Takeaways

MCP is a single open protocol. Wire it once per tool, use it from any compatible client.
Use stdio for local servers (filesystem, local database, scripts). Use Streamable HTTP for remote services and anything that needs OAuth. The older HTTP+SSE transport is deprecated.
The -- double-dash is required when adding stdio servers - everything after it goes to the server process, not to Claude Code.
Three scopes: local (private to you, this project), project (team-shared via .mcp.json), user (private to you, all projects). Secrets belong in local scope only.
Anthropic maintains seven official reference servers: Everything, Fetch, Filesystem, Git, Memory, Sequential Thinking, and Time. For databases like SQLite, community servers on npm fill the gap.
When something breaks, run the server command directly in your terminal first - stderr almost always tells you exactly what is wrong.

Try this next: Once your first server is connected, see Building Your First MCP Server to flip to the other side and expose your own tools to any MCP-compatible agent.

Guide toolkitcore8 min read