Connect an MCP Server to an AI Assistant

This guide walks you through connecting a Model Context Protocol (MCP) server to an AI assistant, setting up the necessary permissions, and troubleshooting common issues. By the end, you’ll have your assistant able to call external tools and data sources securely.

What You’ll Need

An AI assistant that supports MCP (e.g., Claude Desktop, Cursor, or a custom client).
An MCP server (either a public one or one you’ve built).
Access to the assistant’s configuration files (usually JSON or TOML).
Basic familiarity with command line and JSON syntax.

Step-by-Step

Identify your MCP server’s connection details. Most MCP servers are either HTTP-based (provide a URL) or stdio-based (run as a local process). Check the server’s documentation for the exact command or URL.
Locate your AI assistant’s MCP configuration file. For Claude Desktop, this is usually claude_desktop_config.json in the user’s config directory. For Cursor, it’s in .cursor/mcp.json in your project. If you’re using a custom client, check its docs.

Add the server entry. Open the config file in a text editor. Add a new entry under the mcpServers key. For an HTTP server, it looks like:

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

For a stdio server, use the command and args fields:

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

Set environment variables if needed. If your server requires API keys or other secrets, add an env object inside the server entry. For example:
```
"env": {
  "API_KEY": "your-key-here"
}
```
Never hardcode secrets in plain text if you can avoid it; use environment variables or a secret manager.
Configure permissions. MCP servers often have tool-specific permissions. In the same config file, you may see a permissions or tools section. If not, check the server’s own configuration. For Claude Desktop, you can set permissions like:
```
"permissions": {
  "tools": ["read_file", "write_file"],
  "allow": ["filesystem"]
}
```
This restricts which tools the assistant can call. Adjust to match your security needs.
Restart the AI assistant. After saving the config, fully quit and reopen the assistant application. This reloads the MCP configuration.
Verify the connection. In the assistant, look for a tool or MCP indicator. Try a simple prompt that would invoke a tool from your server, like “List files in the current directory” if you added a filesystem server. If it works, you’re connected.

Common Mistakes

Incorrect JSON syntax. Missing commas or trailing commas break the config. Use a JSON validator if unsure.
Wrong command path. For stdio servers, the command must be in your PATH. Use the full path if not.
Port conflicts. If using an HTTP server locally, ensure the port isn’t already in use.
Forgetting to restart. Many assistants only load MCP configs at startup.
Overly restrictive permissions. If you block a tool the server needs, the assistant may fail silently.

Tips

Start with a simple, well-known server (like filesystem) to test the setup before adding complex ones.
Use relative paths for stdio commands if your assistant runs from a specific directory.
Keep your config file version-controlled to track changes.
For HTTP servers, consider using a reverse proxy like Nginx to handle authentication and SSL.
Check the server’s logs (usually in the terminal) for detailed error messages.

Troubleshooting

If the connection fails, work through these in order:

Check the config file syntax. Run jq . your-config.json to validate JSON. If it errors, fix the syntax.
Verify the server is running. For HTTP servers, curl the URL: curl http://localhost:8000/mcp. For stdio, try running the command manually in a terminal.
Look at the assistant’s logs. Most assistants log MCP errors to a file (e.g., ~/Library/Logs/Claude on macOS). Search for “MCP” or the server name.
Check environment variables. If your server needs an API key, ensure it’s correctly set in the env block. Test by echoing the variable in a terminal.
Simplify permissions. Temporarily set permissions to allow all tools to see if that’s the issue. If it works, narrow down.
Try a different transport. If HTTP fails, try stdio (or vice versa) to isolate the problem.
Update the MCP server. If you’re using a public server, ensure it’s up to date. Run npm update or similar.

Frequently Asked Questions

What is MCP and why use it?

MCP (Model Context Protocol) is a standard that lets AI assistants connect to external tools and data sources securely. It avoids building custom integrations for each assistant.

Can I connect multiple MCP servers?

Yes, just add multiple entries under mcpServers. Each server is independent.

How do I know if my server supports HTTP or stdio?

Check the server’s documentation. Most modern servers support both; the config format differs slightly.

What if my assistant doesn’t show MCP tools?

Ensure the assistant version supports MCP (most recent versions do). Also, check that the server is listed in the config and the assistant was restarted.

Is it safe to give the assistant file access?

It depends on your trust level. Use permissions to restrict tools to specific directories or operations. For sensitive data, use a sandboxed environment.

Can I use MCP with a remote server?

Yes, if the server is accessible via HTTP. Ensure proper authentication (e.g., API keys) is set up.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →