MCP Config JSON Errors: How to Fix Common Mistakes

This guide applies to MCP clients configured with a static JSON file and API key. If your client offers Add custom connector and asks only for a server URL, use Corcava's OAuth flow instead: enter https://app.corcava.com/mcp and authorize in the browser. OAuth avoids storing an API key in JSON.

First: protect the API key

Do not paste a configuration containing a real Corcava API key into an online validator, support message, screenshot, or repository. Replace the key with YOUR_API_KEY before sharing the file, or validate it locally.

If a real key has already been exposed, create a replacement under Corcava Settings → Integrations → Public API, update the client, verify the new connection, and then revoke the old key.

A valid Corcava configuration

For clients that accept the standard mcpServers structure, the Corcava entry is:

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The exact outer structure can vary by client. Use the client's Corcava setup guide when it documents a different transport or configuration shape.

Error 1: trailing commas

JSON does not allow a comma after the final property.

Invalid:

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp",
    }
  }
}

Remove the comma after the URL.

Error 2: comments or annotations inside JSON

Standard JSON does not support // comments, block comments, arrows, or explanatory notes inside the object.

Invalid:

{
  // Corcava server
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp"  ← use this URL
    }
  }
}

Keep explanations outside the code block. A configuration labeled “valid” must contain only valid JSON.

Error 3: single quotes or unquoted keys

JSON requires double quotes around property names and string values.

Invalid:

{
  mcpServers: {
    'corcava': {
      'url': 'https://app.corcava.com/mcp'
    }
  }
}

Use the valid configuration shown above.

Error 4: mismatched braces

Every opening { or [ must have a matching closing brace or bracket. Formatting the file with a local JSON parser usually makes missing braces easy to locate.

Invalid:

{
  "mcpServers": {
    "corcava": {
      "url": "https://app.corcava.com/mcp"
    }
  }

The root object is missing its final closing brace.

Error 5: duplicate mcpServers keys

Do not create a second top-level mcpServers object when adding Corcava to an existing configuration.

Invalid structure:

{
  "mcpServers": {
    "first-server": {}
  },
  "mcpServers": {
    "corcava": {}
  }
}

Put both server entries inside one object:

{
  "mcpServers": {
    "first-server": {},
    "corcava": {
      "url": "https://app.corcava.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Error 6: incorrect Authorization value

For static API-key configuration, the header value must contain Bearer, one space, and the key in the same JSON string.

Valid shape:

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Common mistakes include omitting Bearer, inserting a line break, copying leading or trailing whitespace with the key, or putting the key outside the headers object.

Error 7: valid JSON in the wrong client schema

A file can be valid JSON but still be ignored by the MCP client. Check:

• The configuration file is in the location used by the installed client.
• The server entry is inside the field required by that client.
• The endpoint is exactly https://app.corcava.com/mcp.
• The client supports a remote URL in its manual configuration format.
• The file was saved as .json, not .json.txt.

For Claude, ChatGPT, and other clients with an OAuth custom-connector interface, prefer that interface over adapting a legacy JSON example.

Validate locally

From the directory containing the configuration:

python3 -m json.tool your-config.json

Windows PowerShell can parse a file with:

Get-Content ".\your-config.json" -Raw | ConvertFrom-Json | Out-Null

VS Code and many other editors also mark JSON syntax errors locally. Local validation keeps the API key on your machine.

Reload the client

After the JSON validates:

1. Save the file.
2. Fully quit or reload the MCP client according to its setup guide.
3. Reopen it with Corcava enabled.
4. Ask the client to list the Corcava tools.

If the server still does not appear, follow Claude Desktop: Server Not Showing. If the server appears but advertises no tools, use MCP Tools Not Listed.

For both OAuth and API-key setup, see AI Assistant Integration (MCP).