MCP Integration: A Developer's Guide to Connecting AI Agents to Your Existing Stack

What Is MCP Integration?

MCP integration is the process of connecting AI applications like Claude Desktop, Cursor, or custom agents to external tools and data sources through the Model Context Protocol. Developers can integrate MCP servers in three main ways: connecting prebuilt servers, building custom servers with an SDK, or using a managed capability network.

MCP (Model Context Protocol) is an open standard released in November 2024 and donated to the Linux Foundation in December 2025 (Source: modelcontextprotocol.io). It provides a standardized way for AI models to interact with external tools — replacing the fragmented approach of writing custom integrations for each tool. Anthropic announced MCP adoption across the AI industry in 2025 (Source: anthropic.com/news), and the open-source community has built 8,600+ MCP servers as of early 2026 (Source: github.com/modelcontextprotocol).

MCP integration builds on the broader pattern of function calling — providing a standardized way for any LLM to access tools across different providers. If you're new to AI agents, start with our what is AI agent orchestration guide to understand the broader landscape. To choose the right MCP server for your use case, see our MCP server comparison guide.

Before You Start: Choosing Your Integration Path

MCP integration isn't one-size-fits-all. Your stack, use case, and desired complexity determine which path fits. Here's the decision framework:

If you haven't selected a server yet, compare 8 popular MCP servers to find one matching your use case.

Path 1: Connect Claude Desktop to MCP Servers

The fastest path to MCP integration. This assumes you're using Claude Desktop and want to connect to a prebuilt server like filesystem, GitHub, or PulseMCP.

Step 1: Find your Claude Desktop config file

The Claude Desktop config file stores your MCP server connections. Its location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

If the file doesn't exist yet, you can create it. The file follows standard JSON formatting.

Step 2: Add your MCP server configuration

Edit the JSON file and add an mcpServers entry. Here's the configuration for the filesystem server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Step 3: Restart Claude Desktop

After editing the config file, close and reopen Claude Desktop. The MCP server appears in the tools panel on the left sidebar.

You should see your new server listed under "MCP Tools" or a similar section depending on your Claude version.

Adding more servers

You can add multiple servers to the same config file. Here's how to connect PulseMCP (which gives you access to 8,600+ additional MCP servers):

{
  "mcpServers": {
    "pulse": {
      "command": "npx",
      "args": ["-y", "@pulsemcp/core"]
    }
  }
}

Verifying your connection

To confirm your MCP server is working, try asking Claude to perform a task that uses the connected tool. For example:

• "List the files in my configured directory"
• "Show me the recent commits in my GitHub repository"
• "What's the status of my connected services?"

If the MCP server is properly connected, you'll see actual results instead of an error message like "I don't have access to that tool" or "I can't perform this action."

If the connection fails

Common issues and fixes:

• Config file not found: Verify the path matches your OS (see Step 1 above)
• JSON syntax error: Run your config through a JSON validator — trailing commas and missing quotes are common mistakes
• Server package not installed: Run npx -y @modelcontextprotocol/server-filesystem manually to verify the package works
• Permission denied: On macOS, ensure Claude Desktop has file system access in System Settings

Switching between servers

Claude Desktop lets you toggle individual MCP servers on or off without removing them from the config. This is useful when you want to limit which tools are available for a specific task — for example, disabling GitHub access when working on a public repository to prevent accidental commits.

Cursor uses a similar MCP configuration format, but the config file lives in your project directory rather than a global app folder.

Step 1: Create the Cursor MCP config directory

In your project root, create a .cursor folder if it doesn't exist. Inside that folder, create mcp.json:

mkdir -p .cursor
touch .cursor/mcp.json

Step 2: Add your MCP server configurations

Edit .cursor/mcp.json to include the servers you want. Here's a configuration that connects both filesystem and GitHub:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./project-files"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Step 3: Restart Cursor

Close and reopen Cursor. Your MCP servers appear in the Cursor AI panel. The project-local config means each project can have different tool access — useful when working across multiple clients or repositories.

Verifying your connection

Try asking Cursor's AI to perform a task using one of the connected tools. For example: "Show me the files in my project directory" or "What are the recent commits in this repository?"

If the connection works, you'll see actual results. If not, check that the .cursor folder is in your project root and the mcp.json file has valid JSON syntax (no trailing commas, proper quotes).

Other AI IDEs with MCP support

Several other AI-powered IDEs support MCP with similar configuration formats:

• Windsurf: Uses ~/.windsurf/mcp.json for global config or .windsurf/mcp.json for project-local
• VS Code with Copilot: MCP support is experimental; check the VS Code extensions documentation for setup
• JetBrains AI Assistant: Configuration varies by IDE version; see JetBrains documentation

The core config format (mcpServers JSON object) is consistent across these tools, so the servers you configure will work similarly.

Path 2: Connect Cursor and Other AI IDEs

Cursor and similar AI-powered IDEs use a similar MCP configuration format, but with project-local configs instead of global app configs. This approach gives you different tool access per project — useful when different projects have different security requirements or client confidentiality needs.

Why use Cursor over Claude Desktop for MCP?

Cursor is built specifically for code editing, with deep GitHub integration and project-aware context. For development teams, Cursor's project-local MCP configs mean you can share tool configurations through your repo without affecting other projects or team members. Each developer maintains their own config while using the same server definitions.

Other scenarios where Cursor shines: when you need IDE-specific features like symbol navigation, code completion, or language server integrations alongside your MCP tools.

Step 1: Create the Cursor MCP config directory

In your project root, create a .cursor folder if it doesn't exist. Inside that folder, create mcp.json:

# Create the config directory and file
mkdir -p .cursor
touch .cursor/mcp.json

Step 2: Add your MCP server configurations

Edit .cursor/mcp.json to include the servers you want. Here's a configuration that connects both filesystem and GitHub with proper authentication:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./project-files"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Step 3: Restart Cursor

Close and reopen Cursor. Your MCP servers appear in the Cursor AI panel under the tools section. The project-local config means each project can have different tool access — useful when working across multiple clients or repositories.

You can verify the connection by asking Cursor to list files or check your GitHub repository status using natural language.

Adding environment-specific configurations

For production projects, you might want different MCP servers than for development. You can create multiple config files:

• .cursor/mcp.json — development config (includes debugging tools)
• .cursor/mcp.prod.json — production config (includes monitoring tools)

Swap between them by renaming the active config file before starting Cursor.

Common Cursor MCP use cases

Teams commonly use Cursor MCP for:

• Code review automation: Connect GitHub server to automatically fetch PR details and suggest reviews
• Documentation generation: Connect to internal wikis or Confluence for context-aware doc generation
• Database queries: Connect to MCP servers that wrap your internal data tools
• API testing: Connect to HTTP request tools for testing APIs directly in the IDE

Other AI IDEs with MCP support

Several other AI-powered IDEs support MCP with similar configuration formats:

• Windsurf: Uses ~/.windsurf/mcp.json for global config or .windsurf/mcp.json for project-local
• VS Code with Copilot: MCP support is experimental; check the VS Code extensions documentation for setup
• JetBrains AI Assistant: Configuration varies by IDE version; see JetBrains documentation

The core config format (mcpServers JSON object) is consistent across these tools, so the servers you configure will work similarly.

Path 3: Build Custom Integrations with the MCP SDK

When no prebuilt server exists for your tool, you build one. The MCP SDK is available in Python and TypeScript. This path requires basic coding knowledge.

Step 1: Install the FastMCP SDK

Choose your language and run the corresponding install command:

# Python
pip install fastmcp

# TypeScript / Node.js
npm install @modelcontextprotocol/sdk

Step 2: Define your tool handlers

Here's a minimal Python server that exposes a custom data analysis tool:

from fastmcp import FastMCP

mcp = FastMCP("my-data-tool")

@mcp.tool()
def analyze_data(query: str, timeframe: str = "7d") -> str:
    """Analyze data from your internal database.

    Args:
        query: The analysis question
        timeframe: Time window (1d, 7d, 30d)
    """
        # Your custom logic here
    results = f"Analysis for {query} over {timeframe}: [data]"
    return results

@mcp.resource("database://schema")
def get_schema():
    return "Table: users | Columns: id, name, email, created_at"

mcp.run()

Step 3: Start your server and connect

Run your server in the background, then add it to Claude Desktop or Cursor config:

# Run your server
python my_server.py

# Add to Claude Desktop config (~/.config/Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "my-data-tool": {
      "command": "python",
      "args": ["/path/to/my_server.py"]
    }
  }
}

When to choose Path 3

Build a custom MCP server when your internal tool or database doesn't have a public MCP server, and you need custom logic that prebuilt servers can't handle. This is the most flexible path but requires ongoing maintenance as the MCP specification evolves.

If you want to avoid building custom servers, see Path 4 for a managed alternative.

For a full comparison of MCP server options including prebuilt servers, see our server guide.

Path 4: One-Config Integration with Qveris

If managing multiple MCP servers sounds like overhead you don't want, Qveris provides a managed capability layer — one config, 10,000+ capabilities. This path is for developers who want the fastest route to full tool access without configuring individual servers.

How Qveris differs from manual MCP server setup

With manual MCP server setup, you install each server separately:

• Filesystem server for file operations
• GitHub server for repository access
• Slack server for team communication
• Database server for data queries
• ...and so on for each tool you need

Each server requires its own config entry, authentication setup, and update management. With Qveris, you connect one MCP server that routes to 10,000+ capabilities across all these categories.

Step 1: Install Qveris CLI

If you haven't already, install the Qveris CLI:

npm install -g qveris

# Or use npx without installing
npx -y @qverisai/cli --version

Step 2: Get your API key

Sign up at qveris.ai to get your free API key. The free tier includes access to 100+ capabilities; the full suite requires a paid plan.

Step 3: Add Qveris to your MCP config

Add the Qveris MCP server to your Claude Desktop or Cursor config:

// Qveris: One config, 10,000+ capabilities
{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key"
      }
    }
  }
}

After restart, Claude Desktop (or Cursor) gains access to 10,000+ capabilities including filesystem, search, weather, finance, blockchain, healthcare, and more — without installing each MCP server separately. Qveris handles provider selection, fallback logic, and format normalization internally through its capability routing layer.

Understanding capability routing

Traditional MCP setup requires you to know which server provides which capability. With capability routing, you describe what you need in natural language, and the routing layer finds the best matching capability across 10,000+ options. For example:

• "I need to check the weather in Tokyo" → routes to weather capability
• "Get me the current Bitcoin price" → routes to cryptocurrency capability
• "Search for recent news about AI" → routes to search capability

This capability routing means you don't need to manage individual server installations, auth tokens, or update cycles. The routing layer handles this complexity, so your agent can focus on tasks rather than tool management.

When to choose Qveris capability routing over manual MCP setup

The capability routing approach shines when you need broad tool coverage without operational overhead. Consider Qveris when:

• You need 10+ capabilities: Installing and maintaining 10 individual MCP servers takes hours; Qveris capability routing handles this in one config line.
• Your tools lack official MCP servers: Many internal tools, legacy systems, and niche services don't have published MCP servers. Qveris's capability routing can connect to these through its managed integrations.
• You want centralized auth: Instead of managing separate API keys for each MCP server, Qveris capability routing uses a single authentication flow.
• You're prototyping rapidly: Qveris capability routing lets you explore available capabilities before committing to specific server configurations.

Consider manual MCP server setup (Paths 1-3) when you need fine-grained control over a specific tool, want to avoid vendor lock-in, or have strict compliance requirements that mandate direct integrations. The capability routing layer adds a dependency — if that matters for your use case, manual setup is the safer choice.

Step 4: Use Qveris capabilities

Once connected, you can discover and use capabilities through the Qveris CLI:

# List available capabilities
qveris discover "file operations" --json

# Query financial data
qveris discover "cryptocurrency market data" --json

# Access map and location services
qveris discover "geographic data" --json

Comparing the four paths

Here's how the paths compare across key dimensions:

For a full comparison of MCP server options including prebuilt servers and managed approaches, see our server guide.

FAQ

Related Guides