MCP Server JSON: Configuration Examples and Common Mistakes

When people ask about MCP server JSON, they are usually asking about one of two different things. The first is the configuration file that tells an AI client like Claude Desktop which servers to connect to. The second is the JSON-RPC 2.0 message format that client and server use to talk once connected. The files look similar; the problems they cause are completely different.

Getting the configuration right once, and keeping a sanitized copy of it somewhere the team can find, saves repeated troubleshooting. Tools like fenbs hold those configuration notes and proven fixes as context, so the next AI session starts with the working setup rather than the debugging session.

Client configuration JSON

The client configuration file is the JSON file you edit to add, remove, or update MCP server connections. Each AI client stores this file in a different location and uses a slightly different schema, but they follow the same general shape: an object with an mcpServers key whose value is a map of server names to their connection details.

For Claude Desktop, the file is claude_desktop_config.json in the application support directory for your operating system. For Claude Code, MCP servers are added through the claude mcp add command or by editing a configuration file in your project directory. Check Anthropic's current documentation for exact file paths on your platform.

Stdio server configuration

A local server that runs as a child process uses stdio transport. Its config entry specifies the command to run and any arguments. Use absolute paths — relative paths cause the most common startup failures because the client launches the process from a different working directory than you expect.

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/Users/alice/projects/my-server/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb",
        "API_KEY": "sk-..."
      }
    }
  }
}

Put credentials in the env block, not hardcoded in the args array. The env block is still stored in plain text in the config file, so treat the file itself as sensitive and keep it out of version control. The args array is visible in process listings; credentials there are exposed to anything that can list running processes.

Remote server configuration

A remote server that uses Streamable HTTP transport needs a URL rather than a command. Some clients also support a headers field for static API keys, though OAuth is the recommended authentication method for remote servers.

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

For OAuth-protected servers like fenbs, the client handles authentication automatically. You do not need to add a token to the configuration file; the client prompts you to sign in when it first connects.

JSON-RPC messages versus configuration JSON

JSON-RPC is the message format the client and server exchange after they connect. You typically never write these messages by hand; the MCP SDK handles them. But you see them when you use the MCP Inspector to test a server, when you read server logs, or when you debug an unexpected response.

A JSON-RPC request has four fields: jsonrpc (always "2.0"), id (a number or string that matches the response), method (the action to take), and optionally params. A response has jsonrpc, id, and either result or error. An initialize request, for example, sends the client's capabilities and expects the server's capabilities in the result.

JSON Schema is the format used to describe each tool's input parameters. The server declares a JSON Schema for each tool's inputSchema, and the client validates tool calls against it before sending them. See the mcp server spec for the full message format.

Common mistakes in configuration JSON

• Relative path in args: the server process cannot be found because the client starts it from a different directory. Use absolute paths.
• Missing node in command: if your server is a Node.js script, the command should be node, not the script path directly.
• Credentials hardcoded in args instead of env: visible in process listings. Move them to the env block.
• Trailing comma in the last JSON entry: JSON does not allow trailing commas; they cause a parse error when the client reads the file.
• Wrong server name key: the key in mcpServers is a label you choose; the server itself does not know it. Use a descriptive name and be consistent.
• Environment variables that reference shell variables: the env block does not expand $HOME or ~. Write the full absolute path.

When client-specific YAML applies

YAML is not part of the MCP specification. A few AI clients or deployment tools accept YAML as an alternative to JSON for their configuration files, because YAML is more readable for humans and supports comments. The underlying data model is the same.

If a client supports YAML configuration, its documentation will say so. Do not assume a JSON config file can be renamed to .yaml without changes; YAML has different quoting rules and does not use double quotes for all strings the way JSON does.

How to do this with fenbs

1. Create a free account and add a project for your MCP server setup work.
2. After you have a working server configuration, add a sanitized copy as a context note in fenbs: the server name, the command or URL, the env variable names needed (not the values), and the steps to test it.
3. When you fix a configuration problem, add a note about what was wrong and what fixed it. Link it to the task you created for the setup.
4. Connect your AI to fenbs over MCP from Integrations. The configuration for fenbs itself uses the remote HTTP format shown above.
5. When a server updates and the configuration changes, update the context note and add a brief description of what changed.

fenbs does not store secrets. Context notes hold the structure of a configuration and the steps to use it — the environment variable names, the expected format, and the known good state — not the credentials themselves.