MCP

The Sugra API is available as a Model Context Protocol (MCP) server, so AI agents can discover and call all 1,600+ endpoints as tools. Two ways to connect: the hosted server (no install; OAuth or an API key) or the local PyPI package (stdio, API key).

The hosted Sugra API MCP server is published in Anthropic's Connectors Directory for Claude on the web, desktop and mobile, Claude Code and Cowork (Add to Claude). It is also listed in the official OpenAI Plugins Directory for ChatGPT and Codex (Add to ChatGPT).

	Hosted	Local package
Endpoint	`https://mcp.sugra.ai/mcp` (Streamable HTTP)	`pip install sugra-api-mcp` (stdio)
Auth	OAuth sign-in, or `Authorization: Bearer YOUR_API_KEY`	`SUGRA_API_KEY` environment variable
Tools	Gateway tools plus the composed agent tools	Gateway tools
Best for	Claude, ChatGPT and Codex (one-click install), remote agents, zero setup	Desktop clients, IDEs, self-hosting, version pinning

Both surfaces authenticate against the same account and draw from the same daily request quota as direct API calls. The package requires Python 3.11+ and is MIT licensed.

Tools

Discovery tools (search, describe, list) run against a bundled catalog of the full endpoint surface, locally and without network calls. Only data requests hit the API.

Tool	Purpose
`fetch_data`	One step: find the best endpoint for a natural-language query and call it
`search_endpoints`	Search the bundled endpoint catalog
`describe_endpoint`	Inspect an endpoint by `operation_id`: parameters, required inputs, `agent_hints` (duration class, concurrency ceiling, bulk cost), `request_body_schema` for JSON-body POSTs
`call_endpoint`	Call an operation by `operation_id`; supports response shaping with `limit`, `fields` (dotted paths), `include_raw`
`list_toolsets`	List catalog groups with endpoint counts and descriptions
`list_sources`	Bundled catalog source metadata
`sugra_entity_screen`	Screen a name against sanctions and watchlists (Sugra Entity)
`sugra_entity_lookup`	Entity lookup by LEI or VAT: registry identity plus screening (Sugra Entity)

Hosted-only agent tools

The hosted endpoint adds composed tools that resolve, snapshot, and chart entities in single calls. They require an infrastructure credential present only on the hosted deployment; stdio and self-hosted installs always expose only the gateway tools.

Tool	Purpose
`resolve_entity`	Free text (ticker, company, indicator, coin, currency pair) to a canonical entity; ambiguous matches return ranked candidates
`get_snapshot`	Entity plus a named recipe to one composed current view with freshness, provenance, and billing blocks; fixed recipe cost of 1-2 requests
`get_timeseries`	Entity plus metric (`price`, `macro_series`, `etf_flows`) to a bounded series with an explicit downsampling flag

Connect a client

Claude (Connectors Directory)

The Sugra API MCP server is published in Anthropic's Connectors Directory, which serves claude.ai, Claude Desktop, Claude Mobile, Claude Code and Cowork:

Add to Claude opens the Sugra API MCP server in the Connectors Directory; in claude.ai it is also under Customize -> Connectors.

Connect it and sign in with your Sugra account.

Claude Code signed in with a claude.ai account picks up connectors added in claude.ai automatically; /mcp lists Sugra.

Already added Sugra to Claude as a custom connector? That connection keeps working and shows under "Custom". Connecting the Sugra API MCP server from the directory as well gives you two connections, so remove the custom one first, then connect from the directory.

ChatGPT and Codex (OpenAI Plugins Directory)

Add to ChatGPT installs the Sugra API MCP server from the OpenAI Plugins Directory. In the Codex app, open Plugins and install it from the same directory.

The Codex CLI connects with your API key, read from the SUGRA_API_KEY environment variable, so the same command works in any shell:

Any other client (hosted, manual setup)

Add this URL as a remote MCP server and sign in with OAuth, or send Authorization: Bearer YOUR_API_KEY:

https://mcp.sugra.ai/mcp

claude.ai, as a custom connector: Customize -> Connectors -> Add custom connector

ChatGPT: Settings -> Connectors -> Add MCP server

Claude Desktop (local, stdio)

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "sugra": {
      "command": "sugra-api-mcp",
      "env": {
        "SUGRA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop; the Sugra tools appear in the tools menu.

Claude Code (CLI)

Signed in with a claude.ai account, the Sugra API MCP server connected from the Connectors Directory already appears in /mcp. Otherwise (an API key, Bedrock or Vertex), add the hosted server with your API key from the SUGRA_API_KEY environment variable, in bash or zsh:

In PowerShell, write the variable as $env:SUGRA_API_KEY.

Local (stdio):

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "sugra": {
      "command": "sugra-api-mcp",
      "env": {
        "SUGRA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Zed, Cline, Continue.dev, Windsurf, and VS Code use the same stdio config shape in their respective MCP settings files.

Sugra API Skills

The MCP server gives an agent the tools. The Sugra API Skills give it the procedure: how to find an operation, how to read the response, how to cite the source.

In ChatGPT and Codex, install the Sugra API Skills from OpenAI's Plugins Directory. In Claude Code:

Other platforms: github.com/Sugra-Systems/sugra-api-skills.

Hosted or local

Prefer hosted when the client cannot launch local processes (claude.ai, ChatGPT, remote agents), when you want the composed agent tools, or when you want the catalog to track the API without reinstalling. Prefer local when the client runs on your machine over stdio, when you want to pin a package version, or when self-hosting the HTTP transport with your own base URL and timeout (SUGRA_API_BASE, SUGRA_TIMEOUT).

Verify the hosted server

Discovery is public; tool calls require auth. A bare request returns 401:

The MCP initialize handshake answers 200 and issues a session id:

Errors and quota

Tool failures return structured JSON, never bare exceptions: upstream_timeout, upstream_connect_error, upstream_transport_error, or an HTTP error with status_code and retry_after. Every error payload carries elapsed_ms. A failure with no structured JSON means your agent harness cut the call; raise the client-side tool timeout.

MCP calls count against your account's daily quota exactly like direct API requests; hosted composed tools charge a fixed recipe cost of 1-2 requests. See Rate limits and errors for plan volumes.

Tools#

Hosted-only agent tools#

Connect a client#

Claude (Connectors Directory)#

ChatGPT and Codex (OpenAI Plugins Directory)#

Any other client (hosted, manual setup)#

Claude Desktop (local, stdio)#

Claude Code (CLI)#

Cursor#

Sugra API Skills#

Hosted or local#

Verify the hosted server#

Errors and quota#