MCP Basics: Giving the Agent New Senses

Tier 1 · Fundamentals 8 min read

The built-in tools (Read, Edit, Write, Bash, Grep) operate on the local filesystem and terminal. They’re powerful, but they can’t query your Supabase database, read a Google Calendar event, search Slack, or pull a GitHub issue. MCP — the Model Context Protocol — is how you give the agent those capabilities without writing a custom tool from scratch.

What MCP is

MCP is an open protocol (published by Anthropic) that defines how an agent connects to external tools and data sources. An MCP server is a small process that speaks this protocol: it declares a list of tools, the agent calls those tools by name, and the server executes them and returns results.

From the agent’s perspective, MCP tools look identical to built-in tools. The agent doesn’t “know” whether mcp__supabase__query_table is a built-in or an MCP server — it just calls it, gets a result, and acts on the result.

From your perspective as the operator, adding an MCP server means:

Install or run the server process.
Register it in .mcp.json.
The agent now has the server’s tools available in every session in that directory.

The .mcp.json file

.mcp.json (at the project root or in ~/.claude/) tells Claude Code which MCP servers to connect at startup. A minimal example:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--supabase-url", "https://yourproject.supabase.co", "--supabase-key", "YOUR_KEY"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

When a session starts, Claude Code reads .mcp.json, launches each server process, and negotiates which tools they expose. Those tools become callable for the duration of the session.

A real example: 16 servers, one agent system

As of mid-2026, the agent system described in Tier 3 runs 16 MCP servers wired into the global ~/.claude/.mcp.json:

google-calendar, obsidian-vault, google-drive, email-fastmail,
email-gmail, slack, canvas-lms, github, coingecko, brave-search,
openclaw-bridge, nutrition, playwright, supabase, linkedin, memory

That’s calendar, two email providers, a notes vault, Slack, a learning management system, GitHub, two financial data sources, a web cockpit bridge, browser automation, a database, LinkedIn, and a hybrid memory layer — all reachable by the same agent that reads and edits files. Adding a new data source means adding one entry to .mcp.json and restarting.

This is why “MCP as new senses” is the right mental model. The agent can read a GitHub issue, check the calendar for a conflict, query the database for the relevant record, and write the fix — all in one session — because each system is an MCP server.

Getting started: three steps

Find or build a server. The MCP registry has official servers for common systems (GitHub, Slack, Google Drive, databases). For internal tools, you can write a server in any language using the MCP SDK.
Add it to .mcp.json. Use the format above: a key (the name the agent will use), a command to start the server, args, and env for secrets.
Start a new session. Claude Code reads .mcp.json on session startup. Open a new claude session and run /doctor to check that the server connected cleanly.

What “tool available” means in practice

When an MCP server connects, its tools show up in the session’s tool list. The agent uses them contextually — if you ask it to “query the tasks table in Supabase,” it will call mcp__supabase__query_table rather than try to write a Python script that does the same thing. The MCP tool is faster and cleaner.

One common mistake: wiring up many MCP servers and then wondering why the agent is slow or why tool calls occasionally fail. Each MCP server is a live process with its own authentication and network dependencies. If a server’s credentials expire or the network times out, that tool fails. The solution is to keep MCP servers that are genuinely needed and check on their health periodically — in a larger system, an automated health check (like the hourly MCP health check running on this system) will catch a downed server before you notice it’s gone.

Next: The Skills System — reusable slash commands that bundle multi-step agent behaviors into a single invocation.