MCP Server Configuration: Local and Remote Connections

Configuring an MCP server connection means telling your AI app where the server is and how to reach it. For Claude Desktop and most other AI clients, this is a JSON config file you edit by hand. The format is the same for every server; what changes is whether the server runs locally or remotely and whether it needs credentials.

Understanding the config structure also tells you how to connect multiple servers at once — you can add as many as you need. A team might run a local file-access server for individual use, a shared project tool like fenbs for the whole team, and a cloud provider's server for infrastructure queries, all connected at the same time.

The config file format

In Claude Desktop, the config is at claude_desktop_config.json in the application support folder. On macOS that's ~/Library/Application Support/Claude/; on Windows it's in the user's AppData/Roaming/Claude/ folder. In Cursor, the equivalent is .cursor/mcp.json in your project folder or home directory. Other clients have similar locations.

The file contains a single mcpServers object. Each key inside it is a name you choose for the server; the value describes how to connect to it.

{
  "mcpServers": {
    "my-server": {
      ... connection settings ...
    },
    "another-server": {
      ... connection settings ...
    }
  }
}

Configuring a local (stdio) server

A local server runs as a subprocess on your machine. The config provides the command to start it, any arguments, and optional environment variables.

{
  "mcpServers": {
    "my-local-tool": {
      "command": "npx",
      "args": ["-y", "my-mcp-package"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

The command is an executable on your PATH. args is the list of arguments. env sets environment variables the server process reads at startup — this is where API keys and secrets go, not in the code. Restart the AI app after saving the config for it to take effect.

The server must be installed before it can be launched. If command is npx, the package is downloaded on first launch. If it's a local path, the binary or script must exist at that path. Check the server's documentation for the exact command.

Configuring a remote (HTTP) server

A remote server runs at a URL and is accessible from any machine. The config provides the URL instead of a command.

{
  "mcpServers": {
    "fenbs": {
      "url": "https://fenbs.ai/api/mcp"
    }
  }
}

For OAuth servers like fenbs, no credential goes in the config file. The client handles authentication through a browser sign-in. When Claude first tries to connect, it will prompt you to authorize via a browser window. The resulting token is stored by the client for the session.

Some remote servers use API key authentication instead of OAuth. In that case, add the key as a header in the config, or follow the server's specific instructions. Each server documents its expected authentication method.

Multiple servers in one config

You can have as many servers as you need in the same config file. Each gets its own key and settings. The AI client connects to all of them at startup and presents the combined set of tools to the AI.

Name your servers clearly. The key you choose becomes the server's identifier in logs and sometimes in error messages. Names like fenbs, google-sheets, or local-files are easier to read than server1 when you're debugging a connection issue.

Environment variables and secrets

Secrets — API keys, database passwords, access tokens — belong in the env block, not in the command or args. The config file itself is readable by anyone with access to your home directory. On shared machines, treat it as you would a .env file: never commit it to a repository, and use your operating system's file permissions to limit who can read it.

For remote OAuth servers, no secrets go in the config at all. The URL is the only setting needed; the OAuth token is handled separately by the client after the browser sign-in.

Testing and troubleshooting connections

After saving the config, restart the AI app and check that the server connected. In Claude Desktop, a connected server shows in the toolbar or a connected tools panel. Try asking the AI to list what tools are available from a specific server to confirm it's working.

If a server doesn't connect, check these things in order: Is the server installed and runnable? Is the command or URL correct in the config? Are any required environment variables set? Did the app restart after the config was saved? For OAuth servers: did the browser sign-in complete successfully?

Claude Desktop logs are useful for diagnosing failures. On macOS, open Console.app and filter by "Claude". On Windows, check the application logs in the user's AppData folder. The log entry for a failed MCP connection usually includes the error from the server.

How to do this with fenbs

1. Create a free account if you haven't already.
2. Open Integrations and find the setup guide for your AI app. It provides the exact config snippet and the OAuth sign-in steps.
3. Add the fenbs entry to your mcpServers config in the app's config file.
4. Restart the AI app. On the first request to fenbs, it will prompt you to sign in with your fenbs account in a browser.
5. Ask your AI to call fenbs_whoami to confirm the connection is working and check which role it has on your boards.

Related: MCP server architecture explains the roles and request flow, and MCP server hosting covers where remote servers run.