MCP

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

	Hosted	Local package
Endpoint	`https://app.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	11 (8 gateway + 3 composed agent tools)	8 gateway tools
Best for	claude.ai, ChatGPT, 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 three 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 the eight 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.ai and ChatGPT (hosted)

Add https://app.sugra.ai/mcp as a connector and sign in with OAuth:

claude.ai: Settings -> 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)

Hosted (OAuth, 11 tools):

Local (stdio, 8 tools):

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.

Hosted or local

Prefer hosted when the client cannot launch local processes (claude.ai, ChatGPT, remote agents), when you want the three 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 plan's daily quota exactly like direct API requests. Per-item bulk endpoints charge one request credit per item (reported in the API's X-RateLimit-Cost header); 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.ai and ChatGPT (hosted)#

Claude Desktop (local, stdio)#

Claude Code (CLI)#

Cursor#

Hosted or local#

Verify the hosted server#

Errors and quota#