ai.sugra/api-mcp

Official11 tools

by Sugra-Systems · Python

Sugra API

Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.

Connects LLM agents to world data through tools and an endpoint catalog.

Topics

data-platformintelligence-infrastructurellm-toolsmcpmodel-context-protocolpython

Captured live from the server via tools/list.

sugra_entity_screen

Screen a person or organization name against the Sugra sanctions corpus. Returns a SCREENING SIGNAL, not a compliance determination. Sugra is a technology provider, not a sanctions authority or consumer reporting agency. PEP and adverse-media coverage is supplementary and non-comprehensive - a `clear` result is not proof of absence, and a `hit` is a candidate match to review, not a finding. Output is COMPACT to protect the agent context budget: `{status, matches:[{name, score, list, type}], disclaimer}`. The verdict `status` is one of `clear`, `review`, or `hit`. The heavy raw fields (match rationale, source ids, publish dates) are dropped; use the Sugra API directly when the full screening envelope is needed. Args: name: The person or organization name to screen (required). country: Optional ISO 3166-1 alpha-2 country to narrow the match. dob: Optional date of birth (YYYY-MM-DD) for a person. nationality: Optional nationality to narrow the match.

Parameters (4)

namestringrequired
countryany
dobany
nationalityany

sugra_entity_lookup

Resolve an entity by identifier and return its composed KYB envelope. `anchor` is `lei` (Legal Entity Identifier, resolved via the GLEIF registry) or `vat` (EU VAT number, validated via the EU VIES service). The result weaves identity, a sanctions screening signal, and - on request - ownership and adverse-media slices. The screening verdict is a SCREENING SIGNAL, not a compliance determination, and any PEP / adverse-media content is supplementary and non-comprehensive. The `disclaimer` field carries this and is always present. Output is COMPACT by default to protect the agent context budget: `{entity:{name, anchor, value, status, country}, screening:{status, top_matches:[...3], hit_count}, ids:{...}, disclaimer}`. Pass `include` to opt INTO fuller per-slice detail, e.g. `include=["ownership","adverse_media"]` adds those slices in full form. On a bad anchor or an API error this returns a clean `{error, detail}` dict rather than raising, so the agent can branch on `result.get("error")`. Args: anchor: Identifier type, one of `lei` or `vat`. value: The identifier value (the 20-char LEI code or the VAT number). include: Optional list of fuller slices to add, e.g. `["ownership", "adverse_media"]`. Omit for the compact default.

Parameters (3)

anchorstringrequired
valuestringrequired
includeany

search_endpoints

Search the bundled Sugra endpoint catalog by natural-language query.

Parameters (4)

querystringrequired
toolsetany
sourceany
limitinteger

describe_endpoint

Describe one Sugra API endpoint by operation_id. Includes agent_hints (duration_class fast/slow/heavy, max_concurrency, bulk billing) so you can budget timeouts and parallelism before calling. POST endpoints with a JSON body also carry request_body_schema (the resolved JSON schema) - construct the `body` argument from it instead of guessing key names.

Parameters (1)

operation_idstringrequired

call_endpoint

Call a Sugra API endpoint by operation_id from the bundled catalog. Plan calls with describe_endpoint's agent_hints: duration_class "fast" usually responds in under ~2s, "slow" usually 1-5s and occasionally 15s+ on a cold upstream, "heavy" can exceed the gateway timeout - keep parallel calls within max_concurrency and prefer small batches. Bulk endpoints bill 1 request credit per body item. Failures return structured errors {error, reason, status_code, elapsed_ms, retry_hint}; after "upstream_timeout" a single retry often succeeds because the aborted attempt warms upstream caches.

Parameters (6)

operation_idstringrequired
paramsany
bodyany
limitany
fieldsany
include_rawboolean

list_toolsets

List endpoint groups available in the bundled catalog.

No parameters.

fetch_data

One-step fetch: find the best Sugra endpoint for the query and call it. Combines search_endpoints + call_endpoint into a single round trip. Use this when you want data without manually picking an operation_id. The full search_endpoints + describe_endpoint + call_endpoint dance is still available when you need explicit control, but for most natural-language queries this tool is enough. Behavior: 1. Search the bundled catalog for the query. Top match wins. 2. If the matched endpoint has required parameters and they are all provided in `params`, call it and return the response. 3. If required parameters are missing, return the candidate endpoints and the missing-params list so the LLM can retry with the correct `params` dict on the next call. Examples: - `fetch_data("US CPI inflation", params={"series_id": "CPIAUCSL"})` → calls /api/v1/fred/series/CPIAUCSL, returns observations. - `fetch_data("Bitcoin price", params={"coin_id": "bitcoin"})` → calls /api/v1/crypto/bitcoin/price. - `fetch_data("Latest financial news")` → news_latest has no required params, returns latest news directly.

Parameters (6)

querystringrequired
paramsany
bodyany
limitany
fieldsany
include_rawboolean

list_sources

List endpoint source families derived from catalog metadata.

No parameters.

resolve_entity

Resolve free text to a canonical market or macro entity. Turns a ticker, company name, macro indicator, coin, or currency pair into the agent plane's ``{namespace, ids}`` entity for use with get_snapshot and get_timeseries. A cross-namespace collision (e.g. a ticker that is both an equity and a coin) returns status "ambiguous" with ranked candidates and NEVER silently picks one; pass type_hint (e.g. "equity", "etf", "coin") to narrow the universe. For compliance KYB lookups by LEI/VAT or sanctions screening use sugra_entity_lookup / sugra_entity_screen instead - this tool is for market-data entities. Args: query: Free-form text - ticker, company, indicator, coin, or pair. type_hint: Optional namespace hint narrowing resolution.

Parameters (2)

querystringrequired
type_hintany

get_snapshot

Composed current view of an entity via a named recipe. Executes a fixed server-side recipe (company_snapshot, etf_snapshot, quote_snapshot, macro_indicator_snapshot, macro_calendar, earnings_snapshot, debt_snapshot) and returns one envelope with freshness, provenance, per-component coverage, and billing. Composed calls charge the recipe's fixed cost (1-2 units) from the daily quota. status "partial" means an optional component was unavailable - the present components are still trustworthy; honor the freshness block (stale=true means the data aged past its budget). Args: recipe: Recipe name from the fixed manifest. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}).

Parameters (2)

recipestringrequired
entityobjectrequired

get_timeseries

Bounded timeseries for an entity: price, macro_series, or etf_flows. Returns points oldest-first with an explicit downsampling flag when the raw series exceeded max_points. etf_flows is filing-cadence (one point per SEC filing refresh), NOT per calendar day, so even a wide window yields a handful of points. Times are UTC. Costs 1 unit per call. Args: metric: One of price / macro_series / etf_flows. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}). granularity: Requested point granularity (default "1d"). max_points: Hard cap on returned points (default 500).

Parameters (4)

metricstringrequired
entityobjectrequired
granularitystring
max_pointsinteger

README.md14 KBView on GitHub

sugra-api-mcp

<p align="center"> <img src="https://app.sugra.ai/images/brand/sugra-app-icon.svg" alt="sugra.ai" width="112" height="112" /> </p> <p align="center"> <a href="https://pypi.org/project/sugra-api-mcp/">PyPI v0.8.2</a> | Python 3.11+ | <a href="https://github.com/Sugra-Systems/prod-sugra-ai-MCP/blob/main/LICENSE">MIT</a> </p>

Gateway connector between LLM agents and world data. Official Model Context Protocol server for the Sugra API, backed by a bundled endpoint catalog and operation_id calls.

Works with Anthropic Claude, OpenAI GPT, Google Gemini, xAI, and any MCP-enabled IDE.

Client details:

Anthropic Claude: Claude Desktop, Claude Code (CLI), claude.ai (web)
OpenAI GPT: ChatGPT (via MCP connector)
Google Gemini: Gemini CLI, Gemini Code Assist (VS Code + JetBrains)
xAI: Remote MCP Tools in xAI SDK and Responses API
IDEs: VS Code (native), Cursor, Zed, Cline, Continue.dev, Windsurf
Custom agents: anything built on the Python or TypeScript MCP SDK

What you get

Current release: eight-tool surface with hosted OAuth activity validation for https://app.sugra.ai/mcp, plus ChatGPT Apps-compatible OAuth tool metadata. Curated tool names such as get_market_price, get_macro_indicator, and get_news are not part of this package. The package exposes exactly eight tools:

Tool	Purpose
`fetch_data`	One-step: find best endpoint for a natural-language query and call it. Combines search + call in one round trip.
`search_endpoints`	Search the bundled endpoint catalog. Runtime search does not fetch `/openapi.json`.
`describe_endpoint`	Inspect an endpoint by `operation_id`, including path, method, parameters, required inputs, `agent_hints`, and `request_body_schema` for JSON-body POST operations.
`call_endpoint`	Call a Sugra API operation by `operation_id`. Arbitrary path calls are no longer supported.
`list_toolsets`	List catalog groups with endpoint counts and descriptions.
`list_sources`	Show bundled catalog source metadata.
`sugra_entity_screen`	Screen a name against sanctions and watchlists (Sugra Entity).
`sugra_entity_lookup`	Composed entity lookup by identifier - `anchor` is `lei` or `vat`, plus the identifier `value`; returns registry identity + screening (Sugra Entity).

call_endpoint and fetch_data both support response shaping with limit, fields, and include_raw. Shaping works on enveloped ({"data": ...}) and envelope-less payloads alike; fields entries may use dotted paths into nested objects (geo.city), and meta.shaped reports what was actually applied (fields_applied / fields_unmatched, limit_applied) rather than echoing the request.

describe_endpoint returns computed agent_hints per endpoint so agents can budget time and parallelism before calling:

duration_class - fast (under ~2s, snapshot-backed), slow (live upstream proxying, occasionally 15s+), or heavy (per-item upstream work, large batches can exceed the gateway timeout)
max_concurrency - advisory ceiling for parallel calls from one session
bulk_cost - on per-item bulk endpoints: 1 request credit per item in the request body (the API reports the total in the X-RateLimit-Cost response header)

Hosted-only agent tools (app.sugra.ai/mcp)

The hosted MCP endpoint at https://app.sugra.ai/mcp serves the same eight tools PLUS three composed agent tools that are not available on stdio or self-hosted installs:

Tool	Purpose
`resolve_entity`	Free text (ticker, company, indicator, coin, currency pair) to a canonical market or macro entity. Ambiguous matches return ranked candidates, never a silent pick.
`get_snapshot`	Entity plus a named recipe to one composed current view with freshness, provenance, coverage, and billing blocks. Composed calls charge a fixed recipe cost (1-2 requests) from the daily quota.
`get_timeseries`	Entity plus metric (`price`, `macro_series`, `etf_flows`) to a bounded series with an explicit downsampling flag.

These three tools wrap an internal composed plane that requires an infrastructure credential available only on the hosted deployment. The tool code ships inside the package, but it is registered only by the hosted HTTP entry point and only when that credential is present - pip install sugra-api-mcp (stdio and self-hosted HTTP) always exposes the classic eight-tool gateway. Hosted-only examples in any documentation are labeled as such. For compliance entity lookups (LEI / VAT, sanctions screening) use sugra_entity_lookup and sugra_entity_screen, which work on every transport.

Installation

bash

pip install sugra-api-mcp

Get a free API key at app.sugra.ai/settings/billing (Free tier: 50 req/day).

Usage with Claude Desktop (stdio)

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: Claude Desktop has no Linux build. On Linux, pip install sugra-api-mcp and use Claude Code (CLI), an IDE client, or the hosted HTTP endpoint below.

json

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

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

Usage with Claude Code (Anthropic CLI)

bash

claude mcp add sugra -- sugra-api-mcp
# then set the env var that sugra-api-mcp reads
export SUGRA_API_KEY=sugra_xxx_...

Or edit ~/.claude/config.json manually with the same shape as Claude Desktop above.

Usage with Cursor, Zed, Cline, Continue.dev, Windsurf

Each of these has an MCP settings file (typically mcp.json or equivalent) with the same stdio config shape as Claude Desktop.

Usage with ChatGPT

ChatGPT supports MCP through its connector UI. Use the hosted HTTP endpoint (below) since ChatGPT does not launch local stdio processes.

Usage over HTTP (claude.ai, ChatGPT, remote agents)

Hosted Streamable HTTP endpoint:

code

https://app.sugra.ai/mcp

Add to claude.ai, ChatGPT, or any Streamable HTTP MCP client. Authenticate with Authorization: Bearer sugra_xxx_....

In claude.ai: Settings -> Connectors -> Add custom connector. In ChatGPT: Settings -> Connectors -> Add MCP server.

CLI

Server startup is unchanged:

bash

sugra-api-mcp
sugra-api-mcp --transport streamable-http --port 8001

Catalog and gateway helpers:

bash

sugra-api-mcp doctor
sugra-api-mcp list-toolsets
sugra-api-mcp search "NASDAQ futures"
sugra-api-mcp describe cot_financial
sugra-api-mcp call quotes_symbol_price --params '{"symbol":"AAPL"}'

Environment variables

Variable	Required	Default	Description
`SUGRA_API_KEY`	Yes (stdio)	-	Your Sugra API key. In HTTP mode with OAuth this becomes a fallback for requests without Bearer
`SUGRA_API_BASE`	No	`https://sugra.ai`	Override for self-hosted or beta environments
`SUGRA_TIMEOUT`	No	`30`	Request timeout in seconds
`SUGRA_MCP_ALLOWED_HOSTS`	No (HTTP)	-	Comma-separated hostnames to allow behind a reverse proxy
`SUGRA_MCP_ALLOWED_ORIGINS`	No (HTTP)	chatgpt.com, claude.ai, cursor.sh + others	Comma-separated allowed Origins for browser-based MCP clients. Applies to BOTH the outer Starlette CORS layer and the inner FastMCP DNS rebinding Origin check, so the two stay in sync. `*` disables the inner Origin check entirely (self-hosted / dev only); Bearer auth still gates tool calls

HTTP transport with OAuth

When running with --transport streamable-http the server allows unauthenticated MCP discovery requests (initialize, notifications/initialized, tools/list, resources/list, prompts/list, and ping) so ChatGPT Apps and other mixed-auth clients can discover tool metadata. CORS is enabled for major MCP clients (ChatGPT, Claude, Cursor) so browser connector UIs can complete the OAuth flow; override the allowlist with SUGRA_MCP_ALLOWED_ORIGINS. Tool calls still require Authorization: Bearer .... Two token formats are accepted:

Raw API key (sugra_...) - passed through as the downstream x-api-key. Compatible with earlier local API-key setups.
OAuth JWT - signature verified against the issuer's JWKS. The audience must match https://app.sugra.ai/mcp, the token must include sugra:read, and hosted access is validated against APP before resolving the user's primary API key. Successful hosted OAuth requests update MCP connection activity in APP.

Variable	Required	Default	Description
`SUGRA_APP_URL`	HTTP + OAuth	`https://app.sugra.ai`	Base URL of the authorization server
`SUGRA_JWKS_URL`	No	`$SUGRA_APP_URL/oauth/jwks.json`	JWKS endpoint
`INTERNAL_API_TOKEN`	HTTP + OAuth	-	Shared secret for the user lookup and MCP activity endpoints on the authorization server. Same value must be set on both the MCP process and the app.sugra.ai Laravel process

Timeouts and the error contract

SUGRA_TIMEOUT caps each downstream HTTP call from this server to the Sugra API (default 30 seconds). It is one link in a longer chain; when a tool call fails, elapsed_ms in the error payload tells you which link cut it:

code

MCP client (agent harness)         own tool timeout, often 60-180s, client-controlled
  -> hosted proxy (app.sugra.ai)   86400s, effectively unlimited
    -> this server (httpx)         SUGRA_TIMEOUT, default 30s
      -> Sugra API -> upstreams    15-60s per upstream call, server-side

Tool failures return structured JSON instead of raising, so agents can pick a retry strategy:

`error` value	Meaning	Retry strategy
`upstream_timeout`	No response within `SUGRA_TIMEOUT` (`elapsed_ms` close to `timeout_s` x 1000)	Retry once: the aborted attempt usually completes server-side and warms upstream caches. Then narrow the request (smaller batch, tighter filters).
`upstream_connect_error`	Could not reach the Sugra API (DNS failure, connection refused)	Retry after a short delay.
`upstream_transport_error`	Connection dropped mid-request	Retry once.
free-text string + `status_code`	The API answered with HTTP 4xx/5xx; `retry_after` included when the API sent a Retry-After header	Honor `retry_after` for 429/503; fix the request for 4xx.
`tool_execution_failed`	Unexpected failure inside the gateway (`exception_type` included)	Report if persistent.

All error payloads carry elapsed_ms. url is present on transport and HTTP errors (not on tool_execution_failed, which can fire before a URL exists). On the three transport errors status_code is null (no HTTP status was received) - consumers comparing status_code numerically should guard for that. If a tool call instead fails with a bare client-side message and no structured JSON, the timeout fired in your agent harness above this server: raise the client's tool timeout, not SUGRA_TIMEOUT.

Examples

Ask Claude:

"Search Sugra endpoints for NASDAQ futures."
"Describe the cot_financial operation."
"Call quotes_symbol_price with symbol AAPL and return only symbol and price."
"List available Sugra toolsets."

Troubleshooting

SUGRA_API_KEY environment variable is required

The server could not find your API key. Depending on how you run it:

As an MCP tool from your client (Claude, ChatGPT, Gemini, xAI, IDE, etc.): check the env block in your MCP config file. Value should be a full key like sugra_ao1_..., not empty and not wrapped in extra quotes.
Shell / CI: export SUGRA_API_KEY=sugra_... before running sugra-api-mcp.
HTTP mode: set via .env or systemd EnvironmentFile, not the shell.

401 Unauthorized or 403 Forbidden in tool responses

Key accepted but rejected. Common causes:

Key was regenerated in app.sugra.ai/settings/billing and your config still has the old one.
Typo - key contains only lowercase letters and digits, no spaces, no trailing newlines.
Free tier was deactivated. Sign in to verify status.

429 Too Many Requests

Hit your plan's daily limit. Response headers include X-RateLimit-Reset with the UTC timestamp when the counter resets (midnight UTC). Upgrade your plan at app.sugra.ai/settings/billing.

Invalid Host header (only if self-hosting HTTP mode)

FastMCP has DNS rebinding protection. Set SUGRA_MCP_ALLOWED_HOSTS to a comma-separated list of the public hostnames your reverse proxy serves. Example: SUGRA_MCP_ALLOWED_HOSTS=mcp.example.com,example.com.

Tool result truncated with meta.truncated notice

Some endpoints return very large payloads (global wildfires, full table catalogs). The client enforces the MCP 25k token limit - when hit, the data list is trimmed and a retry hint appears in meta.truncated.retry_hint. Add narrower filters (country, date range, limit) to get the full result.

Python version 3.11 or higher is required

sugra-api-mcp requires Python 3.11+. Check: python --version. If you have 3.10 or older:

Ubuntu: install Python 3.11 or newer from your distribution packages or the deadsnakes PPA.
macOS: brew install python@3.11
Windows: download from python.org

Then recreate your venv.

Hosted app.sugra.ai/mcp returns 5xx

The hosted endpoint can briefly restart after deploys. Wait 60 seconds and retry. If persistent, email support@sugra.systems.

Debugging tool calls locally

Run with stdio and log JSON-RPC messages:

bash

SUGRA_API_KEY=sugra_... sugra-api-mcp 2>&1 | tee mcp-debug.log

Send manual JSON-RPC from a second terminal using nc or an MCP inspector.

Development

bash

git clone https://github.com/Sugra-Systems/prod-sugra-ai-MCP
cd prod-sugra-ai-MCP
pip install -e ".[dev,http]"
export SUGRA_API_KEY=sugra_...
python -m sugra_api_mcp  # stdio mode
python -m sugra_api_mcp --transport streamable-http --port 8001  # HTTP mode
python scripts/build_endpoint_catalog.py  # rebuild bundled catalog from sibling API openapi.json

Run tests:

bash

pytest

License

Install

Configuration

Environment variables

SUGRA_API_KEYrequiredsecret

Your Sugra API key. Get one free at https://app.sugra.ai/settings/billing (Free tier: 50 req/day).

claude_desktop_config.json

{
  "mcpServers": {
    "api-mcp": {
      "command": "uvx",
      "args": [
        "sugra-api-mcp"
      ],
      "env": {
        "SUGRA_API_KEY": "<YOUR_SUGRA_API_KEY>"
      }
    }
  }
}