Connecting with MCP clients - Cotality developer portal

Most MCP-compatible clients can connect to Cotality MCP with minimal configuration. You need:

The target environment’s MCP endpoint URL — See Quick start
A valid access token — See Authentication

Token configuration required — The clients below (VS Code, Cursor, Claude Code, Windsurf) connect to Cotality MCP with a static bearer token. Include your access token as an Authorization header in your client configuration, as shown in the examples.Automatic OAuth discovery is a separate flow, live in UAT and production, for interactive assistants that ship their own OAuth client and are registered with Cotality — see Choosing an authentication flow. If your client is not one of those, configure the token manually.

Client setup

VS Code
Claude Code
Cursor
Windsurf
Other

1. Create/edit a .vscode/mcp.json file in your project (or open your user-level settings.json).2. Add MCP server configuration:

{
  "servers": {
    "cotality-mcp": {
      "type": "http",
      "url": "https://mcp.cotality.com/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

Avoid committing secrets - If your .vscode/mcp.json is checked into version control, use the input-prompt approach below instead. VS Code will prompt you to paste your token at runtime and store it in local memory.

{
  "servers": {
    "cotality-mcp": {
      "type": "http",
      "url": "https://mcp.cotality.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mcp-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "mcp-token",
      "type": "promptString",
      "description": "Paste your access token here",
      "password": true
    }
  ]
}

3. Reload VS Code. The Cotality MCP tools will appear in your MCP tool list and be available to MCP-aware extensions such as GitHub Copilot.4. A quick test: ask Copilot to “list available Cotality MCP tools”. It should respond with the same tools you see in your MCP tool list.

Option A — CLI commandUse claude mcp add to register the server in one step:

claude mcp add cotality-mcp \
  https://mcp.cotality.com/mcp \
  --transport http \
  --header "Authorization: Bearer <access_token>"

Add the -s user flag to make the server available globally across all projects.Option B — Manual configurationAdd the server to your project-level .mcp.json file (or ~/.claude.json for global access):

{
  "mcpServers": {
    "cotality-mcp": {
      "type": "http",
      "url": "https://mcp.cotality.com/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

Verify the connection:

claude mcp list

You should see cotality-mcp listed. Then start a conversation and ask Claude to “list available Cotality MCP tools” to confirm the tools are loaded.

1. Create/edit a .cursor/mcp.json file in your project root (project-scoped), or ~/.cursor/mcp.json for global access across all projects.2. Add MCP server configuration to the file:

{
  "mcpServers": {
    "cotality-mcp": {
      "url": "https://mcp.cotality.com/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

3. Restart Cursor or reload the window. The Cotality MCP tools will be available in Cursor’s AI chat and composer.4. To verify, open Cursor’s chat and ask the agent to “list available Cotality MCP tools”.

1. Create/edit a ~/.codeium/windsurf/mcp_config.json file.2. Add MCP server configuration:

{
  "mcpServers": {
    "cotality-mcp": {
      "serverUrl": "https://mcp.cotality.com/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

3. Restart Windsurf or reload the window. The Cotality MCP tools will be available in Windsurf’s Cascade AI chat.4. To verify, open a Cascade conversation and ask “list available Cotality MCP tools”.

Any client that supports the Streamable HTTP MCP transport can connect to Cotality MCP. The general configuration pattern is:

Setting	Value
Transport	`Streamable HTTP`
URL	`https://mcp.cotality.com/mcp`
Headers	`Authorization: Bearer <access_token>`

Refer to your client’s documentation for the specific configuration format.

Troubleshooting

401 Unauthorized: Your token may have expired; generate a new one and update it in your client’s configuration.
Connection refused or timeout: Check the endpoint URL and ensure your network allows outbound HTTPS connections.
Client repeatedly prompts for credentials: If a token is missing, invalid, or expired, some clients (e.g., VS Code) fall back to interactive OAuth sign-in, which these token-based setups are not configured for. Ensure you have a valid, unexpired token configured and that your client is set to use it.
A tool is missing from the tool list: tools/list returns only the tools your token is scoped for. Contact your account team if a tool you expect is missing.
Tools not appearing: After updating your configuration, fully restart or reload your client. Some clients cache the tool list and require a fresh connection.

​Client setup

​Troubleshooting

Client setup

Troubleshooting