Claude Code MCP config JSON: project .mcp.json and server setup

Additional instructions for working with Ailoot are in the documentation.

What Is an MCP Server, and Why Does Claude Code Need One?#

Anthropic announced MCP on November 25, 2024, as an open standard. In a year, the protocol became an industry standard: OpenAI, Google DeepMind, and Microsoft support it. The official modelcontextprotocol/servers repository contains reference servers from the MCP project itself (Filesystem, Memory, Sequential Thinking, Fetch, and others); vendors—GitHub, Notion, Stripe, Linear, Cloudflare, and Sentry—publish MCP servers in their own repositories. The total number of servers runs into the thousands in community indexes.

Technically, MCP runs over JSON-RPC 2.0. The architecture is simple: your Claude Code is the client, any service is a server, and the MCP server between them has three entities: tools (what the AI can call), resources (what the AI can read), and prompts (ready-made templates).

Why this matters to a vibe coder: before MCP, every connection between Claude and a third-party service was a separate integration with its own wrapper. With MCP, connecting Postgres, Slack, and GitHub takes three similar commands, and disconnecting them is just as easy when you no longer need the service.

How Is MCP Different from Skills and Subagents?#

A simple table to keep the differences straight:

Practical takeaway: if a task has been specified once and repeats as text, it’s a skill. If the AI needs a live response from an external system, it’s MCP. If the task is long and branching and needs a separate brain, it’s a subagent.

More on the two neighboring mechanisms: Claude Code Skills: How to Build Your Own Library and Claude Code Subagents: 5 Ready-Made Examples.

With MCP Claude Code adds a server: install and verify it in 5 minutes#

Full syntax from the official documentation:

claude mcp add <name> [options] -- <command> [args...]

Three transports are supported: --transport stdio (the default, a local process), --transport http (remote HTTP), and --transport sse (marked deprecated; use only if the server has not migrated yet).

Three scopes are supported through the --scope flag:

• local — only in the current project folder (default).
• project — written to .mcp.json, committed to the repository, and available to the whole team.
• user — global to all projects on the machine.

A minimal example with the MCP project’s reference Filesystem server. It starts in half a minute:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /Users/me/projects
claude mcp list

After list, you’ll see filesystem in the list if the folder from the command exists; without it, the server won’t start. It will be able to see Claude Code’s working folders—that is, the folder where you launched it. I explain why this is so and when this server is actually useful below in 5.2.

To check that MCP is connected, run /mcp inside a Claude Code session. It will show all servers, their status, and their tool lists. Additional instructions for working with Ailoot are available in the documentation. Check the selected MCP server’s README for its specific commands.

stdio or HTTP: Which Transport Should You Choose?#

Comparison by key criteria:

Rule of thumb: anything stored on your disk or in a local database uses stdio. Anything in the cloud uses HTTP. SSE is officially deprecated; don’t choose it.

7 Ready-Made MCP Servers for Entrepreneurs#

MCP Claude Code GitHub integration: issues, pull requests, files, and actions

What it does: gives Claude Code access to issues, pull requests, repository files, and action runs. The server is open source and has more than 30,000 stars on GitHub.

Installation (HTTP, through OAuth):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Alternatively, use stdio through Docker if you need a PAT token instead of OAuth.

Example: “Read the open issues labeled bug, group them by component, and suggest the order in which to close them.” Claude will call GitHub MCP, read all the issues, and return a prioritized list.

Repository: github/github-mcp-server.

5.2. Filesystem MCP — the MCP Project’s Reference Server

What it does: gives the AI access to files on the computer within approved folders. It is released by the MCP project itself; the npm registry lists Model Context Protocol a Series of LF Projects, LLC as the author.

Installation (stdio), with a pinned version:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem@2026.8.31 /Users/me/projects

When Claude Code connects, it passes its working folders to the server, which replaces everything specified in the command. Claude Code’s working folders are the one where you launched it, plus those added with the /add-dir command or the --add-dir flag. You can’t give the server a separate folder with mockups through the command. The folder in the command still has to exist, or the server won’t start.

So in Claude Code, this mostly duplicates the built-in tools. To access files in another folder, /add-dir is enough: after that, Claude Code’s own tools can read the folder too. The server is more useful for programs that don’t have their own file access. In Claude Desktop, another issue can occur: the server’s tools are rejected because their descriptions use an old schema format; this issue is still open.

Give access only to the folders you actually need, both in the command and through /add-dir. Don’t grant access to the disk root—that is the first security hole.

Example: first /add-dir ~/Documents/design, then “Move all the mockups from ~/Documents/design/landing-v3/ into the current project, and rename them according to the hero-*.png convention.”

5.3. Postgres MCP — DBHub (Bytebase)

What it does: connects Claude to Postgres, MySQL, SQL Server, MariaDB, or SQLite. It supports read-only mode so the AI agent can’t drop the database with one command. It is often used as a replacement for Anthropic’s archived reference server, server-postgres.

Installation (HTTP, read-only):

claude mcp add postgres -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb?sslmode=disable" --readonly

For a production database, always use a separate user with read-only grants and anonymize personal data through a VIEW or intermediary API route. Don’t connect to a production database with write permissions.

Example: “Query customers with the expired subscription status from the past month, and list the top 20 by total payment amount.”

Repository: bytebase/dbhub.

5.4. Slack MCP — Team Communication

What it does: gives Claude access to read Slack channels and send messages. Useful for automation: “When the build passes, post in #releases”; “Compile a weekly summary from #engineering.”

Installation (stdio through an npx wrapper, such as @modelcontextprotocol/server-slack or a vendor equivalent):

claude mcp add slack \
  -e SLACK_BOT_TOKEN=xoxb-... \
  -e SLACK_TEAM_ID=T0... \
  -- npx -y @modelcontextprotocol/server-slack

Authorization uses a Slack Bot Token; access is restricted through scopes on Slack’s side. You can give the AI only chat:read and chat:write:user, in which case it won’t be able to edit workspace settings. Check the README for the selected server for current commands; the ecosystem changes quickly.

Example: “Every morning at 9:00, send a list of yesterday’s merged PRs to #daily.”

5.5. Notion MCP — Knowledge Base

What it does: gives Claude access to Notion pages and databases. It’s a knowledge base outside your project: if you keep notes, a customer register, or editorial policy there, the AI can read them.

Installation (HTTP, through OAuth):

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

Alternatively, use Anthropic’s official @makenotion/claude-code-notion-plugin plugin.

Example: “In the Notion database ‘Customers,’ find everyone whose status is ‘active’ and who hasn’t had a call in more than two weeks. Draft an email to each.”

Guide from Notion: developers.notion.com/guides/mcp.

5.6. Sentry MCP — Error Tracking

What it does: connects Claude to errors in your production system. When a page fails with a 500, you can ask, “Show me the 10 latest issues in Sentry for the project and explain the root cause of each,” and get an analysis right away.

Installation (HTTP):

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Authorization is through Sentry OAuth. Access can be limited to a specific project.

Example: “Take the three most frequent issues from the past 24 hours. Explain in plain English what happened and suggest how to fix it.”

Repository: getsentry/sentry-mcp.

MCP Claude Code Playwright integration: workflows in a real browser

What it does: gives Claude a browser. The AI can open a page, click, fill in a form, and take a screenshot. Useful for UI checks, manual testing after publication, and workflow parsing.

Installation (stdio):

claude mcp add playwright -- npx -y @playwright/mcp@latest

Version v0.0.75, released May 7, 2026, is actively maintained by Microsoft (more than 32,000 stars).

Example: “Open our website’s home page, check that all cards display correctly, and take a screenshot on desktop and mobile.”

Repository: microsoft/playwright-mcp.

Check the README for the selected Playwright MCP version for the command with a pinned version, the flag for multiple simultaneous sessions, and common installation errors.

How to Control Security with a PreToolUse Hook#

A SQL-prefix blacklist is not a read-only permission boundary: lowercase SQL, comments, UPDATE, INSERT, ALTER, multiple statements, and side-effecting functions are not covered by three uppercase prefixes. Give the database connection a separate role with read-only grants and verify those grants on a disposable test database. A hook is an extra tool-call control, not a replacement for those permissions.

Here is a deliberately narrow quarantine example: deny all calls through the three named MCP server families until you have reviewed and tested a more specific policy. It blocks reads as well as writes. Match your actual server/tool names; a renamed server, built-in Bash, or another connector is outside these patterns.

Put these separate rules in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__postgres__.*",
        "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""}]
      },
      {
        "matcher": "mcp__slack__.*",
        "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""}]
      },
      {
        "matcher": "mcp__filesystem__.*",
        "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deny-unapproved-mcp.sh\""}]
      }
    ]
  }
}

Save this script as .claude/hooks/deny-unapproved-mcp.sh. It returns the documented PreToolUse decision contract, not the old top-level decision: approve/block form:

#!/bin/bash
printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"This MCP server family is quarantined pending a reviewed policy."}}'

This script does not parse or classify SQL. For a matched call it always denies. Check the matching and hook result in an isolated session before connecting valuable data: SELECT 1, lowercase delete, a comment-prefixed UPDATE, a Slack read or send tool, and a Filesystem read of .env must all be denied when their tool names match. A tool from a different server family must remain outside this example; verify that separate boundary explicitly.

To allow read-only database work, use verified database grants and replace the quarantine with a reviewed policy for the actual tools. For Slack, use a credential without sending privileges when the task only needs reads. For files, restrict the server’s allowed roots and the process’s filesystem permissions. Do not claim this hook prevents access through other tools, shell commands, prompt attachments, or a policy file that the agent can edit.

The same approach is covered in more detail in the Plan Mode in Claude Code guide—there’s similar “check before executing” logic.

What Should You Do If You Have 40+ Tools and Claude Gets Lost?#

According to the Claude Code documentation, it is now enabled by default and doesn’t need to be turned on manually.

Exceptions where Claude Code loads all tools immediately: working through a third-party proxy (when ANTHROPIC_BASE_URL is set to an address other than Anthropic’s), models older than generation 4.5 in Google Cloud, and Microsoft Foundry deployments on Azure. The ENABLE_TOOL_SEARCH variable changes the behavior:

• not set — all MCP tools are deferred and loaded on demand;
• true — the same, plus Claude Code tries to enable search through a proxy;
• auto — threshold mode: while all tool descriptions take up less than 10% of the context window, they load immediately; beyond that, they are deferred;
• auto:N — the same, but with a custom percentage threshold, for example auto:5;
• false — the old behavior; all tools are in context immediately.

For critical tools that must always be visible, there is an alwaysLoad: true flag in .mcp.json next to the server description. Each such tool takes up context from the first minute, so use this only for tools Claude needs in almost every response.

If you have five or more MCP servers and Claude gets confused about which tool to call, first check whether search is disabled: look for ENABLE_TOOL_SEARCH=false in the settings and check whether you’re working through a proxy.

It may also help to reduce context with /compact.

When Do You Not Need MCP: Is a Skill, Subagent, or CLI Better?#

Hierarchy by token cost and complexity:

1. CLI command through Bash — almost free. The AI runs gh pr list, psql -c, or curl and gets a response like a regular terminal user.
2. Skill — cheap. A ready-made prompt template with instructions on what to call and how to process the result. Loaded based on a trigger in the folder name.
3. Subagent — medium. Separate context for a long task, with its own token session.
4. MCP server — expensive. Only tool names remain in context, but the tool description loads when Claude finds it before a call, and service responses can be large: Claude Code warns when a tool response exceeds 10,000 tokens. Plus an OAuth session for HTTP.

Counterintuitive advice: for parsing web pages, working with git, opening PDFs, and using open-source utilities, choose CLI, not MCP. AI can call terminal commands just as well as a person, and tokens are spent only on the command and its response, without tool descriptions or server overhead.

MCP is justified in two cases:

• The service is closed: Slack, Notion, Sentry, Linear. CLI tools exist too, but MCP provides finer-grained access through OAuth and scope controls.
• A live, two-way conversation is needed: AI connects to Postgres, checks the schema, asks a follow-up query, gets the data, and takes the next step. With CLI, this would turn into 10 manual commands.

6 MCP Connection Antipatterns#

1. MCP cabinet. You connected 10 servers “just in case”; Claude gets confused about which tool to call, and their responses clog the context. Solution: keep 3–5 servers for the current project and remove the rest with claude mcp remove.

2. Write access to a production database. You connected Postgres MCP to a production database without --readonly, a separate user, or an allowlist hook. One prompt—“delete the test records”—and production data is deleted. Solution: a separate database role with verified read-only grants, the server’s read-only mode where applicable, and tested tool-call controls. A DROP|TRUNCATE|DELETE prefix blacklist is not sufficient authorization.

3. PII without anonymization. You connected a database containing customers’ emails, phone numbers, and passport details directly. Claude sees the data, and it ends up in Anthropic logs. Solution: a VIEW or intermediary API route that returns masked data such as j***@gmail.com.

4. MCP instead of a skill. You need to “create a sales report in format X”—a routine task solved by a skill with a ready-made prompt. Don’t create an MCP server.

5. MCP instead of an open-source CLI. You need to convert a PDF to text. There’s pdftotext. Don’t build a “PDF MCP”—it just wastes tokens.

6. Not tracking token costs. You can see the connected server in claude mcp list, but not how much it uses in each conversation. After a week, you have no idea that “MCP burned 40% of the context, and I’ve been paying for it this whole time.” Solution: periodically disable unused servers and watch how the usage changes through Claude Code usage limit tracking.

How to Debug an MCP Connection Failure#

Step-by-step checklist:

1. Is the server visible in the list?

   claude mcp list
   

   If not, claude mcp add did not complete. The most common cause is --scope: you added it to local and are checking from another project.

2. Is the server status green?

   claude mcp status <name>
   

   Red means the process did not start (for stdio) or the server did not respond (for HTTP).

3. Do the server logs say anything useful?

   claude mcp logs <name>
   

   If you see a stack trace, the problem is usually with the package (npx could not find it, or the Node version is below 20).

4. Is the OAuth callback failing to return? The problem is usually --callback-port or a network filter. Forward a specific port:

   claude mcp add --transport http --callback-port 8765 [name] [url]
   

5. Tool name conflict? Two servers expose a tool with the same name, and Claude calls the wrong one. Use Tool Search (see the previous H2) or manually remove the extra server with claude mcp remove.

6. Can’t see claude.ai extensions (connectors)? This is a known issue: extensions (connectors) from the claude.ai web interface are not available to Claude Code when it uses an API key. Solution: connect MCP through the CLI, not the web interface.

What’s Next: OAuth, Your Own MCP Servers, and the Plugin Marketplace#

The Plugin Marketplace speeds things up for anyone who doesn’t want to remember installation commands. The format is a .claude-plugin/marketplace.json manifest that describes a set of servers in one package.

Install a plugin from the marketplace:

claude plugin install <plugin-name>

A plugin can contain several MCP servers, skills, and subagents at once—a packaged setup for a specific scenario: e-commerce, marketing, or a legal department.

Write your own MCP server according to the modelcontextprotocol.io specification. A minimal template uses Anthropic’s Python or TypeScript SDK; then describe the tools and connect a transport. The complexity is comparable to writing a REST API with FastAPI.

If your project already has a configured CLAUDE.md and an understanding of context engineering, adding your own MCP takes a day. Without those, it’s better to learn the basics first.

To continue working with models, go to Ailoot.