LLM Agents Guide

A practical, step-by-step guide to connecting your AI agent to MCP servers — with real configuration examples. New to the protocol itself? Start with What is an MCP? first.

This guide walks through connecting an MCP-compatible AI client to an MCP server, from your first local install to running several servers together. It assumes no prior MCP experience, but does assume you’re comfortable editing a JSON file or running a terminal command.

Before you start

You’ll want:

  • An MCP-compatible client installed — for example Claude Desktop, Claude Code, Cursor, or Windsurf.
  • For servers written in Node.js/TypeScript: Node.js installed, so npx is available on your machine.
  • For servers written in Python: uv installed, so uvx is available.
  • Any credentials the specific server needs (a GitHub token, database connection string, API key, etc.) — use scoped, least-privilege credentials wherever the service supports them.

Step 1: Find your client’s configuration

Most desktop clients configure MCP servers through a JSON file. In Claude Desktop, it’s usually reachable from Settings → Developer → Edit Config, and lives on disk at:

macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json
Windows:  %APPDATA%\Claude\claude_desktop_config.json

Claude Code and several other clients also support MCP servers, typically through a command-line interface or a project-level config file, in addition to (or instead of) a global JSON file. The server entries look the same either way — run claude mcp --help, or check your client’s own docs, for the exact current commands.

Step 2: Add a local (stdio) server

Local servers run as a subprocess on your machine. Here’s a filesystem server, one of the most common starting points, added to a client’s config:

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

command is the executable to run, and argsis the list of arguments passed to it — here, the path the server is allowed to read and write. Save the file, then fully restart your client (quit and reopen, not just close the window) so it picks up the change.

Step 3: Add a remote (hosted) server

Remote servers are reached over HTTP instead of being run locally:

{
  "mcpServers": {
    "example-remote": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The exact field names for remote servers vary slightly between clients as this part of the protocol has evolved, so always follow the specific instructions on the server’s own listing — every AllMCPs directory entry includes the setup snippet its maintainer provides.

Common setups

A few of the most popular categories to start with:

  • Filesystem — read and write local files, useful for coding and research agents.
  • GitHub — read issues and pull requests, or open new ones, from chat.
  • Databases (Postgres, SQLite) — query your data in plain language.
  • Web search / fetch — let your agent search the web or read a specific page.
  • Memory — give your agent persistent memory of facts across sessions.
  • Team tools (Slack, Notion, Google Drive) — connect your agent to where your team already works.

Browse working servers in each of these categories on the categories page.

Security best practices

  • Only install servers from sources you trust, and check a listing’s health/verification status on AllMCPs before connecting.
  • Review exactly which tools a server exposes before enabling it — don’t grant an untrusted server broad filesystem or account access it doesn’t need.
  • Use scoped, least-privilege API keys and tokens, and rotate them periodically.
  • Be cautious with servers that feed untrusted external content (web pages, emails, documents) back to your agent — hidden instructions in that content can attempt to manipulate the model, a risk known as prompt injection. Review any high-stakes action before it runs.
  • Remove servers you’re no longer using, and keep the ones you keep up to date.

Troubleshooting

Server doesn’t show up in the client

Almost always a JSON syntax error — a trailing comma or missing quote will silently break the whole config file. Validate it, then fully quit and reopen the client (not just close the window).

“Command not found” errors

The client sometimes can’t see the same PATH your terminal uses, especially on macOS when the app is launched from Finder. If npx or uvxisn’t found, try using the full path to the executable (find it with which npx in a terminal) in the command field, and use absolute paths in args rather than relative ones.

Server starts, then immediately crashes

Check that any required environment variables or API keys are set correctly and haven’t expired.

Remote server rejects the connection

Confirm the token or header you’re sending is current and formatted exactly as the server expects.

Advanced: combining multiple servers

A single client can hold multiple entries under mcpServersat once — there’s no limit to running a filesystem server, a GitHub server, and a database server side by side. This is where MCP starts to feel less like a single integration and more like a toolbox: an agent that can read your code, check open issues, and query production data in the same conversation, choosing which tool to reach for as the task requires.

Next steps