How to Use MCP Servers with Claude Code (Visual Setup Guide)

Claude Code is one of the most powerful AI coding agents available today. But out of the box, it operates within a limited sandbox — it can read and write files, run terminal commands, and not much else. What if you need Claude Code to browse the web, query a database, interact with GitHub issues, or send a Slack message?

That is where MCP servers come in.

In this guide, you will learn exactly what the Model Context Protocol (MCP) is, how MCP servers extend Claude Code's capabilities, and how to set up the most popular MCP servers step by step. We will also show you how SuperBuilder eliminates the complexity of MCP configuration entirely with its built-in skills system.

What Is MCP (Model Context Protocol)?

The Model Context Protocol is an open standard created by Anthropic that defines how AI models communicate with external tools and data sources. Think of it as a universal adapter layer: instead of every AI tool building custom integrations for every service, MCP provides a single protocol that any tool can implement.

An MCP server is a lightweight process that exposes a set of tools (functions the AI can call), resources (data the AI can read), and prompts (templates the AI can use). When Claude Code connects to an MCP server, it gains access to all the tools that server provides.

Here is a simple way to think about it:

• Claude Code alone: Can read/write files, run shell commands
• Claude Code + MCP servers: Can browse the web, query databases, manage GitHub repos, send messages, generate images, and anything else you can expose through a tool

The protocol uses JSON-RPC over standard I/O (stdio) or HTTP, making it straightforward to implement in any language.

Why MCP Matters for Developers

Before MCP, extending an AI agent's capabilities meant writing custom plugins with proprietary APIs for each platform. If you built an integration for one tool, you had to rebuild it from scratch for another. MCP changes this by providing:

• Interoperability: One MCP server works with Claude Code, Claude Desktop, and any other MCP-compatible client
• Composability: You can run multiple MCP servers simultaneously, giving Claude Code access to dozens of tools at once
• Simplicity: The protocol is lightweight — a basic MCP server can be written in under 100 lines of code
• Security: Tools declare their capabilities upfront, and the client (Claude Code) controls which tools get called

Popular MCP Servers for Claude Code

The MCP ecosystem has grown rapidly. Here are the most widely used MCP servers that developers pair with Claude Code.

Filesystem Server

The official @modelcontextprotocol/server-filesystem gives Claude Code controlled access to read and write files in specified directories. While Claude Code already has file access, the MCP filesystem server adds fine-grained permission controls and the ability to restrict access to specific paths.

Use cases: Sandboxed file operations, controlled access to configuration directories, working with files outside the project root.

GitHub Server

The @modelcontextprotocol/server-github connects Claude Code to the GitHub API. It can create issues, open pull requests, review code, manage branches, search repositories, and more.

Use cases: Automated PR reviews, issue triage, repository management, code search across organizations.

Slack Server

The @modelcontextprotocol/server-slack lets Claude Code read and send Slack messages, manage channels, and search conversation history.

Use cases: Automated standup reports, incident response, team notifications, searching for context in Slack threads.

Browser / Puppeteer Server

The @anthropic/server-puppeteer gives Claude Code a headless browser it can control — navigating pages, clicking elements, filling forms, and taking screenshots.

Use cases: Web scraping, testing web applications, filling out forms, capturing visual evidence of bugs.

Database Servers (PostgreSQL, SQLite)

Database MCP servers like @modelcontextprotocol/server-postgres and @modelcontextprotocol/server-sqlite let Claude Code query databases directly, inspect schemas, and run SQL statements.

Use cases: Data analysis, schema exploration, writing and testing queries, debugging data issues.

Setting Up MCP Servers with Claude Code (CLI Method)

The standard way to configure MCP servers with Claude Code involves editing a JSON configuration file. Let us walk through setting up three popular servers.

Prerequisites

Before you begin, make sure you have:

• Claude Code installed (npm install -g @anthropic-ai/claude-code)
• Node.js 18 or later
• The relevant API keys (GitHub token, Slack token, etc.)

Step 1: Configure the GitHub MCP Server

First, install the GitHub MCP server globally:

npm install -g @modelcontextprotocol/server-github

Next, open your Claude Code MCP configuration file. This lives at ~/.claude.json in your home directory:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

You can also use the Claude Code CLI to add it directly:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

After restarting Claude Code, you will see the GitHub tools available. You can verify by asking Claude Code to list your recent repositories or create a test issue.

Step 2: Configure the Slack MCP Server

Install and configure the Slack server similarly:

npm install -g @anthropic/server-slack

Add it to your ~/.claude.json:

{
  "mcpServers": {
    "github": { "..." : "..." },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T01234567"
      }
    }
  }
}

To get a Slack bot token, you need to create a Slack App in the Slack API dashboard, add the appropriate OAuth scopes (channels:read, chat:write, search:read, etc.), and install it to your workspace.

Step 3: Configure the PostgreSQL MCP Server

For database access:

npm install -g @modelcontextprotocol/server-postgres

Add the configuration:

{
  "mcpServers": {
    "github": { "..." : "..." },
    "slack": { "..." : "..." },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/mydb"
      ]
    }
  }
}

After adding all three, your ~/.claude.json file contains the complete configuration. Restart Claude Code, and it will connect to all three MCP servers on launch.

Common CLI Setup Issues

Setting up MCP servers via the CLI works, but developers frequently run into problems:

• JSON syntax errors: A single misplaced comma in ~/.claude.json breaks all MCP connections
• Path issues: The npx command may resolve to different Node versions depending on your shell configuration
• Token management: API keys stored in plain text in a JSON file are easy to leak
• Version conflicts: MCP server packages can conflict with each other or with your project's dependencies
• Debugging: When an MCP server fails to start, Claude Code often gives minimal error output, making it hard to diagnose
• Restart requirement: Every configuration change requires restarting Claude Code

These friction points are exactly why tools like SuperBuilder exist.

The SuperBuilder Approach: One-Click MCP Skills

SuperBuilder is a desktop application built on top of Claude Code that replaces manual MCP configuration with a built-in skills system. Instead of editing JSON files and managing npm packages, you enable capabilities with a single toggle.

How SuperBuilder Skills Work

Under the hood, SuperBuilder runs its own MCP server (superbuilder-skills) that automatically registers with Claude Code on startup. When you enable a skill in the settings panel, SuperBuilder activates the corresponding tool on its MCP server — no restart required.

The architecture looks like this:

1. SuperBuilder starts an HTTP-based MCP server on 127.0.0.1:3457
2. It writes the server configuration to ~/.claude.json automatically
3. When Claude Code spawns, it connects to the SuperBuilder MCP server
4. Enabled skills expose their tools through this single connection

This means you get all the benefits of MCP without any of the configuration overhead.

Built-In Skill: Web Browser

SuperBuilder's web browser skill is not a headless Puppeteer instance — it is a persistent BrowserWindow with a dedicated session (persist:skills-browser). This means:

• Cookies and login state persist between requests. Log into a service once, and Claude Code can access it in future sessions.
• Full Chrome DevTools rendering. No headless quirks or missing features.
• Visual feedback. You can open the browser window and watch Claude Code navigate in real time.

Available tools include browser_navigate, browser_click, browser_type, browser_get_content, browser_screenshot, browser_execute_js, browser_list_tabs, and browser_switch_tab.

To enable it, go to Settings, then Skills, and toggle on "Web Browser." That is it.

// What you'd need in ~/.claude.json for Puppeteer:
{
  "mcpServers": {
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/server-puppeteer"],
      "env": { "PUPPETEER_HEADLESS": "false" }
    }
  }
}

// What you need in SuperBuilder:
// Toggle: ON

Built-In Skill: Image Generation

The image generation skill connects to OpenAI's DALL-E API, letting Claude Code create images directly within your conversation. This is useful for generating placeholder assets, creating diagrams, or producing visual content as part of a development workflow.

The skill uses native fetch to communicate with the DALL-E API, so there are no additional dependencies to install. Just add your OpenAI API key in the skill settings and enable it.

Built-In Skill: Database Queries

SuperBuilder's database skill lets you register database connections and query them directly from Claude Code. It supports:

• register_db_connection: Add a database by providing a connection string
• db_list_tables: See all tables in the connected database
• db_schema: Inspect the schema of a specific table
• db_query: Run SQL queries and get results
• db_describe_all: Get a full overview of the database structure

This is particularly powerful for debugging data issues. You can ask Claude Code to "check if there are any orphaned records in the orders table" and it will write and execute the query, then analyze the results.

CLI Setup vs. SuperBuilder: Side-by-Side Comparison

How to Build Custom MCP Servers

The MCP ecosystem is open, and building your own server is straightforward. This is useful when you need Claude Code to interact with an internal API, a proprietary service, or any tool that does not have an existing MCP server.

Basic MCP Server Structure

An MCP server needs to do three things:

1. Declare its tools (what functions it provides)
2. Handle tool calls (execute the function when Claude Code invokes it)
3. Communicate via the MCP protocol (JSON-RPC over stdio or HTTP)

Here is a minimal MCP server in TypeScript using the official SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-custom-server",
  version: "1.0.0",
});

// Declare a tool
server.tool(
  "get_weather",
  "Get the current weather for a city",
  {
    city: z.string().describe("The city name"),
  },
  async ({ city }) => {
    // Your implementation here
    const weather = await fetchWeather(city);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(weather, null, 2),
        },
      ],
    };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Building a Custom Skill for SuperBuilder

If you are using SuperBuilder, you can also build skills that plug into its MCP infrastructure. SuperBuilder skills follow a consistent pattern:

1. Create a skill module that exports tool handlers
2. Register the skill with the SuperBuilder skills MCP server
3. Add a configuration entry so users can enable/disable it

The skill system uses the same MCP primitives under the hood, so any MCP server you build can also be wrapped as a SuperBuilder skill. This gives you the best of both worlds: the skill works as a standalone MCP server for CLI users, and SuperBuilder users get the one-click experience.

Tips for Building Reliable MCP Servers

Based on our experience building SuperBuilder's built-in skills, here are some practical recommendations:

Keep tool descriptions clear and specific. Claude Code uses the tool description to decide when to call it. Vague descriptions like "interact with the service" lead to misuse. Be explicit: "Search for Slack messages matching a query in a specific channel."

Return structured data. Instead of returning free-form text, return JSON that Claude Code can parse and reason about. This makes follow-up questions more reliable.

Handle errors gracefully. If an API call fails, return a clear error message as the tool result rather than throwing an exception. Claude Code can often retry or try an alternative approach if it understands what went wrong.

Implement timeouts. Network requests can hang indefinitely. Always set reasonable timeouts (10-30 seconds for API calls, 60 seconds for browser operations) and return timeout errors so Claude Code does not get stuck waiting.

Log for debugging. Write logs to stderr (for stdio servers) or a log file. When something goes wrong, you will be glad you have visibility into what the server was doing.

Security Considerations for MCP Servers

When you connect MCP servers to Claude Code, you are giving an AI agent access to external services. This comes with real security implications that you should think through before enabling any server in a production environment.

Principle of Least Privilege

Only grant the minimum permissions each MCP server needs. For the GitHub server, use a fine-grained personal access token scoped to specific repositories rather than a classic token with full repo access. For database servers, connect with a read-only user unless you specifically need write access.

Token Storage

The CLI approach stores tokens in ~/.claude.json as plain text. Anyone with read access to your home directory can see them. Consider using environment variables sourced from a secrets manager instead of hardcoding values in the JSON file. SuperBuilder encrypts credentials in its app settings, which provides a layer of protection that the raw JSON approach does not.

Network Exposure

MCP servers that use HTTP transport (rather than stdio) listen on a network port. Always bind to 127.0.0.1 (localhost only) rather than 0.0.0.0 to prevent external access. SuperBuilder's built-in MCP server binds to 127.0.0.1:3457 by default, ensuring it is only accessible from the local machine.

Audit Tool Usage

Keep an eye on what tools Claude Code is calling and with what arguments. Unexpected tool calls — like a database query that drops a table or a browser navigation to an unfamiliar URL — can indicate a prompt injection or a misunderstanding. SuperBuilder's conversation view shows every tool call and its result inline, making it easy to audit what happened during a session.

Advanced MCP Patterns

Once you have basic MCP servers running, there are several advanced patterns that unlock more powerful workflows.

Chaining Multiple MCP Servers

One of MCP's strengths is composability. You can run multiple servers simultaneously, and Claude Code will select the right tool from the right server based on context. For example:

• GitHub + Slack: "Create a GitHub issue for this bug, then post a summary in the #engineering Slack channel"
• Browser + Database: "Check the production dashboard for any error spikes, then query the logs database for details"
• Filesystem + Image Generation: "Generate a hero image for the landing page and save it to the public/images directory"

Claude Code handles the orchestration automatically — it will call the GitHub tool to create the issue, then call the Slack tool to post the message, all within a single conversation turn.

Resource Subscriptions

MCP servers can expose resources — read-only data that Claude Code can access without calling a tool. This is useful for providing context like database schemas, API documentation, or configuration files. Resources can also support subscriptions, notifying Claude Code when the underlying data changes.

Prompt Templates

MCP servers can provide prompt templates — pre-built prompts that guide Claude Code through complex workflows. For example, a database MCP server might offer a "migration review" prompt that instructs Claude Code to check a migration file against the current schema and flag potential issues.

Troubleshooting MCP Server Connections

Even with the best setup, things can go wrong. Here are the most common issues and how to fix them.

Server Not Connecting

Symptom: Claude Code does not show the MCP server's tools as available.

Fixes:

• Verify ~/.claude.json is valid JSON (use cat ~/.claude.json | python -m json.tool)
• Check that the command path is correct (run the MCP server command manually in your terminal)
• Ensure the required environment variables are set
• Restart Claude Code after configuration changes

Tools Not Being Called

Symptom: Claude Code acknowledges the tool exists but never calls it.

Fixes:

• Check the tool description — it may be too vague for Claude Code to know when to use it
• Try explicitly asking Claude Code to use the specific tool
• Verify the tool's input schema matches what Claude Code expects

Timeout Errors

Symptom: Tool calls fail with timeout errors.

Fixes:

• Increase the timeout in your MCP server implementation
• Check network connectivity to external APIs
• For database servers, verify the connection string and that the database is accessible

Authentication Failures

Symptom: Tools return 401 or 403 errors.

Fixes:

• Verify API tokens have not expired
• Check that tokens have the required scopes/permissions
• For OAuth-based services, ensure the refresh token flow is working

Getting Started with SuperBuilder

If you want to skip the manual configuration entirely and start using MCP-powered tools with Claude Code immediately, SuperBuilder is the fastest path.

1. Download SuperBuilder from superbuilder.sh
2. Open the app and create your first project
3. Go to Settings then Skills
4. Enable the skills you want (web browser, image generation, database)
5. Start a conversation — Claude Code now has access to all enabled tools

No JSON files to edit. No npm packages to install. No restart required.

SuperBuilder also provides a visual interface for managing your conversations, a built-in file browser, project organization with Drive, and debug mode for complex troubleshooting — all built on top of the same Claude Code engine you already know.

Real-World Workflows: MCP Servers in Practice

To make this concrete, here are three workflows that developers use daily with MCP-powered Claude Code.

Workflow 1: Bug Investigation

A user reports a bug in your web app. You paste the error description into Claude Code. With MCP servers enabled, Claude Code can:

1. Search your GitHub issues to check if this bug has been reported before (GitHub MCP)
2. Open the production URL and reproduce the issue visually (Browser skill)
3. Query the production database for affected records (Database skill)
4. Create a detailed GitHub issue with screenshots and data (GitHub MCP)
5. Post an update in the team's Slack channel (Slack MCP)

Without MCP, you would need to do steps 2 through 5 manually, switching between browser tabs, database clients, and Slack. With MCP, Claude Code handles the entire investigation in a single conversation.

Workflow 2: Data Migration Validation

You have written a database migration and need to verify it works correctly. With the database MCP server connected, you can ask Claude Code to:

1. Inspect the current schema before the migration
2. Run the migration
3. Compare the schema after migration to verify the changes
4. Run validation queries to ensure data integrity
5. Generate a summary report

Workflow 3: Content Generation Pipeline

For teams that generate marketing or documentation content, the combination of browser, image generation, and filesystem MCP servers creates a powerful pipeline. Claude Code can research a topic by browsing competitor pages, generate visual assets with DALL-E, write the content, and save everything to the correct project directories — all in one session.

Summary

MCP servers are the key to unlocking Claude Code's full potential. They let you extend a capable coding agent into a tool that can interact with virtually any service or data source.

Whether you choose the CLI approach (editing ~/.claude.json and managing server processes manually) or the SuperBuilder approach (toggling skills on and off in a visual interface), the underlying protocol is the same. Your choice depends on how much setup overhead you want to manage.

For developers who want to get started quickly and focus on building rather than configuring, SuperBuilder provides the smoothest experience — built-in web browsing, image generation, and database skills work out of the box with a single click.

Ready to supercharge Claude Code with MCP? Download SuperBuilder and start using skills today.