Configure an MCP client

Connect

Examples use https://app.astrato.io, the default Astrato application and API host. If your organization provides a private or custom deployment origin, replace the Astrato origin in the MCP and OAuth discovery URLs below.

• MCP URL: https://app.astrato.io/mcp
• Transport: remote Streamable HTTP
• Authentication: OAuth or an Astrato Personal Access Token (PAT)
• OAuth discovery: https://app.astrato.io/.well-known/oauth-protected-resource/mcp

Use OAuth for interactive MCP clients. The client opens Astrato’s consent page and stores tokens for the authorized user and tenant. A PAT is useful for development and clients that support static bearer headers. See Authentication for PAT safety and lifecycle.

In MCP Inspector, select Legacy for the connection mode.

OAuth client setup

Astrato publishes OAuth discovery metadata from the MCP URL. Use the client-specific configuration below; provide a client ID only where that section requires one.

Codex

[mcp_servers.astrato]
url = "https://app.astrato.io/mcp"
scopes = ["workspace:read", "workspace:write", "sl:read", "sl:write", "sl:version", "data:query"]

Visual Studio Code

{
  "servers": {
    "astrato": {
      "type": "http",
      "url": "https://app.astrato.io/mcp"
    }
  }
}

Cortex Code

{
  "type": "http",
  "url": "https://app.astrato.io/mcp",
  "oauth": {
    "client_name": "Cortex Code",
    "scope": "workspace:read workspace:write sl:read sl:write sl:version data:query"
  }
}

CoCo CLI

{
  "mcpServers": {
    "astrato": {
      "type": "http",
      "url": "https://app.astrato.io/mcp"
    }
  }
}

Claude Code

Claude Code shares the connectors from your Claude account, so if Astrato is already connected in Claude, no configuration is needed. For a standalone setup, use one of the two routes below, not both. The Claude Code section of Connect an AI assistant gives the command-line steps.

Personal access token: send the token in an Authorization header, as described in Connect with a personal access token.

OAuth: this route needs a client ID and callback port that Astrato registers for you. Ask your Astrato contact for both, then configure them as below. Do not add an Authorization header to this configuration.

{
  "mcpServers": {
    "astrato": {
      "type": "http",
      "url": "https://app.astrato.io/mcp",
      "oauth": {
        "clientId": "<astrato-issued-client-id>",
        "callbackPort": 61578
      }
    }
  }
}

The callback port must match the registered callback exactly, for example http://localhost:61578/callback.

Hosted ChatGPT and Claude connectors

Set up hosted connectors as described in Connect an AI assistant for Claude, or ChatGPT. Hosted clients supply their own public OAuth identity, so do not configure a client secret. If authorization fails, you cannot update the hosted client yourself; follow the provider’s reauthorization or support flow.

If an OAuth-capable client continues using an old registration or redirect after its configuration changes, clear that client’s stored MCP authorization and reconnect.

OAuth connection or callback errors

For separately installed desktop or CLI MCP clients, update to the latest supported release, restart the client, and retry authorization. If you use both a desktop application and a separately installed CLI—for example, Codex and Codex CLI—check each for updates; updating one does not necessarily update the other. For hosted clients, follow the hosted-connector guidance.

If an error reports a missing issuer, check whether the authorization callback contains iss matching the authorization server’s advertised issuer. If it does, investigate the client’s callback handling. If it is missing or differs, investigate the authorization server. Updating the client does not resolve every OAuth error.

When reporting a persistent failure, include the client name, version, and exact error. Do not share authorization codes, tokens, or complete callback URLs.

Several connectors and accounts

A client can hold several connectors pointing at different accounts or environments, and a connector can be re-pointed at another account at any time. When you mention an account or environment, the agent calls astrato_get_context on each relevant connector and reports the signed-in email, role and tenant. If results change unexpectedly between calls, such as a different number of semantic layers, check identity again.

Connectors can run different tool contract versions at the same time. astrato_get_context returns the toolContract each one supports; a feature introduced in a later contract is not available on an older connector. Every query returns publishedRevision: when it differs between two related queries, the layer’s definitions may have changed between them.

Connect with a Personal Access Token

Supply the PAT as an Authorization: Bearer header. For JSON-configured clients:

{
  "mcpServers": {
    "astrato": {
      "type": "http",
      "url": "https://app.astrato.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}

Do not pass a PAT through command-line arguments. Use OAuth when the client supports it. Otherwise, use the client’s protected secret storage or a user-only local configuration, and follow that client’s instructions for supplying sensitive headers. Do not put a PAT in a shared configuration file or commit it to source control.