Claude Code MCP: project config and connection checks

When to use

• Your team wants shared server names and connection details with authentication managed for each user.[1]

When not to use

• The server documentation has not been reviewed, or you plan to announce success solely because the JSON parses.[1]

Diagnose three separate layers

Start with configuration shape, then server connectivity, then the tools required by the task. The documentation distinguishes HTTP from stdio: HTTP entries use a URL, while stdio starts a local command with arguments. Do not place a remote URL in an entry without type; the documentation says that entry is treated as an invalid stdio configuration.[1]

A project-scoped HTTP example

{
  "mcpServers": {
    "demo-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

[1]

The official CLI shape can generate project configuration with claude mcp add --transport http demo-server --scope project https://example.com/mcp. That URL is a placeholder; running it does not imply a successful connection. Share the connection description needed by the team and follow the specific server documentation for authentication.[1]

Distinguish states with management commands

• Use claude mcp list to check whether the expected name is configured.
• Use claude mcp get demo-server to inspect transport, scope and endpoint.
• Use /mcp in the session to inspect server status and follow the documented authentication or project approval process.
• After connecting, use a read task without side effects to check the actual tool and response. A server name is not evidence of a capability.

[1]

What was verified here

The JSON parses locally, and fields, project scope and management commands were checked against the documentation. No server was registered, no authentication was initiated and no MCP tool was called. Record configuration errors, connectivity errors, authentication errors and tool results separately so the next step targets the correct layer.[1]