Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.
ai.sugra/api-mcp — MCP Server
The ai.sugra/api-mcp Model Context Protocol (MCP) server acts as a gateway between LLM agents and world data. It exposes eight tools and a bundled endpoint catalog, enabling agent workflows to access external resources through MCP.
🛠️ Key Features
Gateway for LLM agents to world data
Eight MCP tools
Bundled endpoint catalog
Package referenced as sugra-api-mcp
🚀 Use Cases
Use MCP to connect LLM agents to external/world data
Discover and consume endpoints via a bundled catalog
⚡ Developer Benefits
MCP-based integration for agent tool use
Endpoint catalog support for structured access patterns
⚠️ Limitations
Limited to the provided set of tools and the bundled endpoint catalog (eight tools total)
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.
Parameters4
name
string
required
Person or organization name to screen (required).
country
any
optional
Optional ISO 3166-1 alpha-2 country to narrow the match.
dob
any
optional
Optional date of birth for a person, YYYY-MM-DD.
nationality
any
optional
Optional nationality to narrow the match.
Raw schema
{
"type": "object",
"properties": {
"name": {
"description": "Person or organization name to screen (required).",
"title": "Name",
"type": "string"
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional ISO 3166-1 alpha-2 country to narrow the match.",
"title": "Country"
},
"dob": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional date of birth for a person, YYYY-MM-DD.",
"title": "Dob"
},
"nationality": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional nationality to narrow the match.",
"title": "Nationality"
}
},
"required": [
"name"
],
"title": "sugra_entity_screenArguments"
}
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.
Parameters3
anchor
string
required
Identifier type: lei (GLEIF) or vat (EU VIES).
value
string
required
The identifier value: 20-character LEI or the VAT number.
include
any
optional
Optional fuller slices to add, e.g. ownership, adverse_media. Omit for the compact default. profile and screening are already in the compact core and are not extra slices.
Raw schema
{
"type": "object",
"properties": {
"anchor": {
"description": "Identifier type: lei (GLEIF) or vat (EU VIES).",
"enum": [
"lei",
"vat"
],
"title": "Anchor",
"type": "string"
},
"value": {
"description": "The identifier value: 20-character LEI or the VAT number.",
"title": "Value",
"type": "string"
},
"include": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional fuller slices to add, e.g. ownership, adverse_media. Omit for the compact default. profile and screening are already in the compact core and are not extra slices.",
"title": "Include"
}
},
"required": [
"anchor",
"value"
],
"title": "sugra_entity_lookupArguments"
}
search_endpoints
Search the bundled Sugra endpoint catalog by natural-language query.
Use this to pick an operation_id. It does not fetch data. Typical loop:
1. search_endpoints(query) -> ranked hits with required_parameters
2. describe_endpoint(operation_id) -> params, request_body_schema, agent_hints
3. call_endpoint(operation_id, params=..., body=...) or fetch_data(query, params=...)
Filter with toolset or source only after list_toolsets / list_sources;
a misspelled filter is an error, not a silent empty result.
Examples:
- search_endpoints("US CPI inflation")
- search_endpoints("AAPL price", toolset="markets")
- search_endpoints("container ship AIS", toolset="network")
Parameters4
query
string
required
Natural-language search over the bundled catalog. Name the instrument, series, place, or task (examples: 'US CPI', 'AAPL quote', 'North Sea AIS'). Returns ranked operation_id hits with required_parameters. Then call describe_endpoint on a hit before call_endpoint.
toolset
any
optional
Optional catalog group filter (markets, macro, news, network, ...). Call list_toolsets for the live names. An unknown value returns error unknown_toolset with known_toolsets rather than an empty hit list.
source
any
optional
Optional source-family filter as listed by list_sources (macro, markets, ...). An unknown value returns error unknown_source with known_sources.
limit
integer
optional
Maximum ranked hits to return. Default 10. Does not call the Sugra API; this only bounds the catalog search list.
Raw schema
{
"type": "object",
"properties": {
"query": {
"description": "Natural-language search over the bundled catalog. Name the instrument, series, place, or task (examples: 'US CPI', 'AAPL quote', 'North Sea AIS'). Returns ranked operation_id hits with required_parameters. Then call describe_endpoint on a hit before call_endpoint.",
"title": "Query",
"type": "string"
},
"toolset": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional catalog group filter (markets, macro, news, network, ...). Call list_toolsets for the live names. An unknown value returns error unknown_toolset with known_toolsets rather than an empty hit list.",
"title": "Toolset"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional source-family filter as listed by list_sources (macro, markets, ...). An unknown value returns error unknown_source with known_sources.",
"title": "Source"
},
"limit": {
"default": 10,
"description": "Maximum ranked hits to return. Default 10. Does not call the Sugra API; this only bounds the catalog search list.",
"title": "Limit",
"type": "integer"
}
},
"required": [
"query"
],
"title": "search_endpointsArguments"
}
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. Call this after search_endpoints and before
call_endpoint when you need the exact parameter names and examples.
Parameters1
operation_id
string
required
Catalog operation_id from search_endpoints (or from list_toolsets drill-down). Unknown ids return error unknown_operation_id.
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.
Parameters6
operation_id
string
required
params
any
optional
Query and path parameters for this operation_id. Keys and types are operation-specific - call describe_endpoint(operation_id) first to get the exact parameter names, types, and examples. Omit if the operation takes none.
body
any
optional
JSON request body for a POST operation, matching the request_body_schema returned by describe_endpoint(operation_id): a JSON object for most operations, or a JSON array when that schema's top-level type is array. Omit for GET operations.
limit
any
optional
Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path.
fields
any
optional
Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key.
include_raw
boolean
optional
If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false.
Raw schema
{
"type": "object",
"properties": {
"operation_id": {
"title": "Operation Id",
"type": "string"
},
"params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Query and path parameters for this operation_id. Keys and types are operation-specific - call describe_endpoint(operation_id) first to get the exact parameter names, types, and examples. Omit if the operation takes none.",
"title": "Params"
},
"body": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "JSON request body for a POST operation, matching the request_body_schema returned by describe_endpoint(operation_id): a JSON object for most operations, or a JSON array when that schema's top-level type is array. Omit for GET operations.",
"title": "Body"
},
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path.",
"title": "Limit"
},
"fields": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key.",
"title": "Fields"
},
"include_raw": {
"default": false,
"description": "If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false.",
"title": "Include Raw",
"type": "boolean"
}
},
"required": [
"operation_id"
],
"title": "call_endpointArguments"
}
list_toolsets
List catalog groups with endpoint counts and short descriptions.
Use the group names as the toolset filter on search_endpoints. This
does not call the Sugra API; it reads the bundled catalog.
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.
Parameters6
query
string
required
Natural-language request for data (examples: 'US CPI', 'Bitcoin price', 'latest news'). The tool picks the top catalog match and calls it. If required params are missing it returns needs_params instead of guessing.
params
any
optional
Parameters for the auto-selected endpoint. If omitted and the best-match endpoint has required parameters, the tool returns that endpoint's required_parameters and examples so you can retry with them filled in.
body
any
optional
JSON body for an auto-selected POST operation; the tool returns the request_body_schema to fill when the match needs one. Pass a JSON object or a JSON array as that schema's top-level type dictates.
limit
any
optional
Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path.
fields
any
optional
Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key.
include_raw
boolean
optional
If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false.
Raw schema
{
"type": "object",
"properties": {
"query": {
"description": "Natural-language request for data (examples: 'US CPI', 'Bitcoin price', 'latest news'). The tool picks the top catalog match and calls it. If required params are missing it returns needs_params instead of guessing.",
"title": "Query",
"type": "string"
},
"params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Parameters for the auto-selected endpoint. If omitted and the best-match endpoint has required parameters, the tool returns that endpoint's required_parameters and examples so you can retry with them filled in.",
"title": "Params"
},
"body": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "JSON body for an auto-selected POST operation; the tool returns the request_body_schema to fill when the match needs one. Pass a JSON object or a JSON array as that schema's top-level type dictates.",
"title": "Body"
},
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Bounds ONLY the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). No such list, or several, means the limit does not apply. Keys beside the list such as total and count are not rewritten, and lists nested inside records are never truncated. meta.shaped reports limit_applied and records_path.",
"title": "Limit"
},
"fields": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional projection of keys to keep on each record of the records list: the data list, a bare top-level array, or the list inside an object data when exactly one of these keys holds a list: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (for example data.items). Keys beside that list such as total and count stay. If a field names a key of data itself, or of a payload without data, that object is projected instead; an object data without such a list is otherwise kept whole. Dotted paths (geo.city) walk nested objects. If no field matches, nothing is removed. meta.shaped reports fields_applied, fields_unmatched and records_path. Omit to keep every key.",
"title": "Fields"
},
"include_raw": {
"default": false,
"description": "If true, attach the original unshaped payload under raw when it fits the size cap; otherwise meta.raw_omitted explains why. Default false.",
"title": "Include Raw",
"type": "boolean"
}
},
"required": [
"query"
],
"title": "fetch_dataArguments"
}
list_sources
List source families in the bundled catalog with endpoint counts.
Use the family names as the source filter on search_endpoints. This
does not call the Sugra API.
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. Crypto aliases resolve too (e.g. "bitcoin" -> the
BTC coin entity). Status "low_confidence" means the best match cleared
resolution but scored weakly - verify the returned entity before
building on it, or re-query with a more specific name or type_hint. 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.
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": ...}).
Parameters2
recipe
string
required
entity
object
required
Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored.
Bounded timeseries for an entity: price, macro_series, etf_flows or
etf_monthly_flows.
Returns points oldest-first with an explicit downsampling flag when the
raw series exceeded max_points. Times are UTC. Costs 1 unit per call.
The two ETF flow metrics answer different questions and are not
interchangeable. ``etf_flows`` is an ESTIMATE at filing cadence: one point
per SEC filing refresh, so ``t`` is a filing date and even a wide window
yields a handful of points. ``etf_monthly_flows`` is the fund's own
creations and redemptions from its NPORT-P filing, so ``t`` is a calendar
month (``YYYY-MM``) and each point carries the three filed components -
sales, reinvestment, redemption - beside the net.
Two things to read before quoting etf_monthly_flows. NPORT-P is filed per
SERIES, so for a fund with more than one share class the figures cover
every class and the payload says so in ``multi_class_series``; where the
class count is unknown it says ``class_scope`` instead of staying silent.
And a fund that files no NPORT-P at all, such as a commodity trust, is not
an error: the call returns status ``partial`` with an empty point list and
a ``reason``.
Args:
metric: One of price / macro_series / etf_flows / etf_monthly_flows.
entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}).
granularity: Requested point granularity (default "1d").
max_points: Hard cap on returned points (default 500).
Parameters4
metric
string
required
entity
object
required
Entity dict from resolve_entity ({namespace, ids}). Extra keys are ignored.
Published in Anthropic's Connectors Directory. Available in Claude on the web, desktop and mobile, Claude Code and Cowork. Published in the official OpenAI Plugins Directory. Available for ChatGPT and Codex.
Give any AI agent access to 1,600+ data endpoints across markets, economics, companies, government, news, climate, maritime and entity screening - through one MCP server.
Works with ChatGPT, Claude, Gemini, xAI, Cursor, VS Code and any MCP client.
Official Model Context Protocol server for the Sugra API: one connector, a bundled endpoint catalog, and structured tool results with source attribution on every answer.
See it in action
An agent answering a real question end to end - resolving entities, pulling live snapshots and history, and citing the source and freshness on every number:
More examples:
Macro research - one prompt builds a full G7 inflation and policy-rate table, each cell dated and sourced, with the unavailable ones flagged rather than faked:
Cross-domain snapshot - Brent crude, marine weather and regional risk pulled together for a shipping desk, each with its source and timestamp:
What a session looks like
Hosted MCP transcript (the three composed tools shown here run on the hosted endpoint). Captured example - wording and figures vary by run and as new BLS data is published:
text
User: Where does US inflation stand, and how has it trended over the past year?
resolve_entity("US inflation")
-> macro indicator cpi_us (U.S. Bureau of Labor Statistics)
get_snapshot("cpi_us")
-> latest reading with freshness, provenance and quota cost
get_timeseries("cpi_us", metric="macro_series", range="1y")
-> 12 monthly points with an explicit downsampling flag
Agent: US CPI printed 2.9% year over year in the latest release, down from
3.5% twelve months earlier - a steady decline since spring.
Source: U.S. Bureau of Labor Statistics via the Sugra API.
Every tool result carries structured metadata - source attribution, freshness, and rate-limit cost - so agents can cite sources and budget requests instead of guessing.
How it works
flowchart LR
A["AI agent<br/>(ChatGPT, Claude, Gemini, xAI, IDEs)"] --> B["Sugra MCP<br/>gateway tools, plus agent tools when hosted"]
B --> C["Sugra API<br/>1,600+ endpoints, 36 data domains"]
C --> D["160+ primary sources<br/>markets, economics, government,<br/>news, climate, maritime"]
Behind the gateway sits the Sugra API: 160+ primary sources - sovereign statistics agencies, central banks, intergovernmental bodies and more - feeding 1,600+ endpoints across 36 data domains. The server ships a bundled catalog of the full endpoint surface, so discovery (search, describe, toolsets) runs locally without network calls; only actual data requests hit the API.
What agents build with it
The Sugra API skills live in Sugra-Systems/sugra-api-skills. The server serves five of them as MCP resources (sugra://skills/...) from a pinned commit of that repository: resources/read the URI after connect.
Agent skills
These skills teach the catalog loop. They do not add MCP tools. Connect the Sugra MCP server separately (hosted or local). The plugin package for each agent lives in Sugra-Systems/sugra-api-plugins.
Or copy the skill folders of sugra-api-skills into the agent's skills directory.
ChatGPT
The skills install from OpenAI's Plugins Directory. The MCP server attaches as a hosted connector at https://mcp.sugra.ai/mcp (permanent alias https://app.sugra.ai/mcp).
Six workflow prompts ship with the server and turn these into one-click flows in clients that surface MCP prompts:
Market and macro research - "Compare inflation and central bank policy rates across the G7." (macro_briefing)
Equity snapshots with sources - "Where does NVIDIA stand today - price, profile, and market backdrop?" (market_snapshot)
Sanctions and compliance screening - "Screen this supplier and resolve its LEI identity." (sanctions_screening)
Sector comparison - "Energy versus technology: valuations and flows side by side." (sector_compare)
Climate, maritime and trade intelligence - "Red Sea shipping this week: chokepoint transits, crude price, and weather on the route." (earth_conditions plus the transport and commodities catalog)
Source discovery - "What does the catalog offer for fixed income, and from which institutions?" (source_overview)
Every answer carries source attribution and freshness metadata, so agents cite instead of guessing.
Hosted MCP (recommended)
No install. In Claude, ChatGPT and Codex, add the Sugra API MCP server from a directory:
Claude (web, desktop, mobile, Claude Code and Cowork): Add to Claude opens the Sugra API MCP server in Anthropic's Connectors Directory; connect it and sign in with your Sugra account. In claude.ai the directory is under Customize > Connectors. Claude Code signed in with a claude.ai account picks the connector up automatically; /mcp lists it.
ChatGPT and Codex: Add to ChatGPT opens the Sugra API MCP server in the OpenAI Plugins Directory.
Any other MCP client, or a manual setup, points at the hosted Streamable HTTP endpoint:
code
https://mcp.sugra.ai/mcp
The gateway tools plus the composed agent tools resolve_entity, get_snapshot and get_timeseries
OAuth sign-in through the Claude and ChatGPT connector flows, or Authorization: Bearer sugra_xxx_... with an API key
As a custom connector in claude.ai: Customize -> Connectors -> Add custom connector
In ChatGPT: Settings -> Connectors -> Add MCP server
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.
Local package
Runs on your machine over stdio (or self-hosted HTTP) with an API key:
bash
pip install sugra-api-mcp
Eight gateway tools
stdio for desktop clients and IDEs, Streamable HTTP for self-hosting
The same call through an agent: connect the server to your client (next section) and ask "What is AAPL trading at? Use Sugra." The agent finds quotes_symbol_price in the catalog and calls it with the symbol.
Connect your client
Supported clients:
Anthropic Claude: Claude Desktop, Claude Code (CLI), claude.ai (web)
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.
Restart Claude Desktop. Sugra tools appear in the tools menu.
Claude Code (Anthropic CLI)
Signed in to Claude Code with a claude.ai account? Add to Claude connects the Sugra API MCP server from the Connectors Directory in claude.ai, and it appears in /mcp without any local install. To run the local package instead:
bash
claude mcp add sugra -- sugra-api-mcp
# then set the env var that sugra-api-mcp readsexport SUGRA_API_KEY=sugra_xxx_...
Or edit ~/.claude/config.json manually with the same shape as Claude Desktop above.
To install the skills as a plugin (separate from the MCP server):
Run gemini mcp list to check the connection, then enter /mcp in an
interactive session to inspect the available tools. A local stdio connection
shows the eight gateway tools in Tool reference; the hosted
endpoint also shows the three hosted-only agent tools.
If a local server does not connect from a new directory, review and trust that
workspace with gemini trust before retrying.
Each of these has an MCP settings file (typically mcp.json or equivalent) with the same stdio config shape as Claude Desktop.
ChatGPT
Add to ChatGPT installs the Sugra API MCP server from the OpenAI Plugins Directory. Or add the hosted HTTP endpoint (below) as an MCP connector, since ChatGPT does not launch local stdio processes.
HTTP (claude.ai, ChatGPT, remote agents)
In claude.ai, Add to Claude connects the Sugra API MCP server from Anthropic's Connectors Directory; in ChatGPT, Add to ChatGPT installs it from the OpenAI Plugins Directory. For a manual setup or any other Streamable HTTP MCP client, use the hosted endpoint:
code
https://mcp.sugra.ai/mcp
Authenticate with OAuth in the connector flow or with Authorization: Bearer sugra_xxx_....
As a custom connector in claude.ai: Customize -> Connectors -> Add custom connector.
In ChatGPT: Settings -> Connectors -> Add MCP server.
Tool reference
The local package exposes eight gateway tools. The hosted endpoint adds three composed analysis tools on top (see Hosted MCP above). 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, records_path, order, kept_end) rather than echoing the request. limit and fields work on the records list: the envelope data list, a bare top-level array, or the one list inside an object data when exactly one of data, entries, events, history, items, observations, points, records, results, rows, series, timeseries holds a list (for example data.items on the latest news, data.observations on a FRED series). When data has no such single list but every one of its values is an object holding exactly one list named observations, as with several named sub-series side by side, limit bounds each data.<key>.observations list on its own; fields there still names keys of data. Keys beside that list, such as total and count, stay as sent, and lists nested inside records are never truncated. A fields entry that names a key of data itself projects that object instead, and a projection that matches nothing leaves the payload whole. meta.shaped.limit_applied says whether the bound took effect, and meta.shaped.records_path names the list used (data, data.<key>, data.*.observations, or null when no records list was used). limit keeps the newest end of the records list when every record carries one date or period key (such as date, period or year) in one format and the list runs one way by it: the last N records of an oldest-first list, in their order, or the first N of a newest-first list. Otherwise it keeps the first N records. Whenever a limit bounds a records list, meta.shaped.order says asc, desc or unknown and meta.shaped.kept_end says newest or first, each as a map by sub-series name for sibling sub-series. A top-level JSON array (or scalar) is always wrapped as {"data": ...} so the MCP result stays an object; otherwise FastMCP output validation reports the successful call as an error and drops the rows.
fields takes at most 32 paths, each at most 256 characters and 16 dotted parts; past any of these the call answers projection_too_large before any request is made. With fields, one projection also visits at most 100,000 list items, runs for at most 5 seconds, and takes a response of at most 2,000,000 characters of JSON before projection. That bound sits far above the 25k token limit on the result, which applies after projection: a 16-day weather forecast is about 295,000 characters before fields=["daily"] cuts it to fit. None of these bounds applies without fields. Shaping runs on its own pool of two worker threads, never on the event loop: at most 8 jobs run or wait for a worker, 4 of them for one caller, and a call that finds no free slot within 2 seconds answers server_busy with scope shaping or caller_shaping.
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, etf_monthly_flows) to a bounded series with an explicit downsampling flag. etf_flows estimates at filing cadence; etf_monthly_flows is the fund's own NPORT-P monthly creations and redemptions.
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.
User-facing configuration for local installs, MCP clients, Docker stdio, and
directory sandboxes (for example Glama Try in Browser). Set only this:
Variable
Required
Default
Description
SUGRA_API_KEY
For API calls
-
Your Sugra API key (sugra_...). Get a free key at app.sugra.ai/register (Free tier: 50 req/day). Not needed to start the server: catalog tools (search_endpoints, describe_endpoint, list_toolsets, list_sources) work without it; API-calling tools return a structured missing_api_key error until it is set. In HTTP mode with a client Bearer token this is only a fallback.
Optional overrides (leave unset unless you need them):
Variable
Default
Description
SUGRA_API_BASE
https://sugra.ai
Override the Sugra API base URL (self-hosted or beta API only).
SUGRA_TIMEOUT
30
Downstream HTTP timeout in seconds for calls from this server to the Sugra API.
Operator-only settings for self-hosted Streamable HTTP (reverse proxy CORS/hosts,
OAuth authorization-server wiring, and shared secrets) are documented in
docs/self-hosting.md. Do not put operator secrets into
public directory sandboxes.
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. 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.
Most users should use the hosted endpoint https://app.sugra.ai/mcp instead of
self-hosting OAuth. If you run your own HTTP process, see
docs/self-hosting.md.
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.
query_too_long
A search_endpoints or fetch_data query has more than 64 terms or 1000 characters (max_terms and max_chars included). A term is a run of two or more ASCII letters or digits, and repeats count; nothing was searched
Shorten the query to the instrument, series, place or task.
projection_too_large
A fields projection passed one of its bounds. limit_kind names it: fields (more than 32 paths), path_chars (a path over 256 characters), path_parts (a path over 16 dotted parts), rows (over 100,000 list items visited), shaping_ms (over 5 seconds) or raw_chars (a response over 2,000,000 characters before projection). limit, actual, field_index (from 0, for path_chars and path_parts) and operation_id are included, never the field text; the first three kinds are refused before any request is made
Name fewer or shorter fields, add limit, narrow the request, or omit fields.
server_busy
A concurrency limit was reached. scope is tool_calls, search or shaping for a server-wide limit, caller_tool_calls, caller_search or caller_shaping for the limit on one caller. With shaping or caller_shaping the API request was already made and its response was dropped; with any other scope the call did no work
Retry after a few seconds.
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
Looking for get_market_price, get_macro_indicator, or get_news? Those curated tool names appear in some older directory listings and never shipped in this package - use fetch_data for one-step natural-language calls or search_endpoints plus call_endpoint for explicit routing.
missing_api_key in tool responses
The server starts and lists its tools without a key, but API-calling tools (call_endpoint, fetch_data, the entity tools) return {"error": "missing_api_key"} until the server can find one. 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.
sugra-api-mcp doctor reports whether the key is visible to the process.
401 Unauthorized or 403 Forbidden in tool responses
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). Plans: sugra.systems/api/pricing.
Invalid Host header (only if self-hosting HTTP mode)
FastMCP has DNS rebinding protection for public hostnames behind a reverse
proxy. See docs/self-hosting.md for the allowed-hosts
setting.
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. The trim keeps the newest end of the list by the same order rule as limit, else its first records, and meta.truncated.order and meta.truncated.kept_end say which (asc, desc or unknown; newest or first). When not even one record fits under the limit, the result is a response_too_large error instead. 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.
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/sugra-api-mcp
cd sugra-api-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
python scripts/build_endpoint_catalog.py --source https://sugra.ai/openapi.json # from the live spec# On DRIFT, catalog-parity.yml opens or updates PR branch ci/catalog-resync.
Run tests:
bash
pytest
Docker
Build the image from the repository root:
bash
docker build -t sugra-api-mcp .
Run in stdio mode (the default entrypoint) for MCP clients that spawn a local process:
bash
docker run -i --rm -e SUGRA_API_KEY=sugra_... sugra-api-mcp
Run the Streamable HTTP transport on port 8001 with Docker Compose:
bash
export SUGRA_API_KEY=sugra_...
docker compose up -d
Then point your MCP client at http://localhost:8001/mcp. The compose service
passes SUGRA_API_KEY and the optional overrides (SUGRA_API_BASE,
SUGRA_TIMEOUT) from your shell when set, and checks container health against
http://localhost:8001/health. Reverse-proxy and OAuth operator settings are
documented in docs/self-hosting.md.
Every response the application sends, errors included, carries the header
Server: sugra-api-mcp. So does uvicorn's own 400 for a request it cannot
parse under the httptools parser, which the http extra installs and uvicorn
picks by default; under the h11 parser that 400 goes out without the header.
Set SUGRA_MCP_SERVER_VERSION=1 (or true, yes, on) in the server's
environment to add the package version to that header
(sugra-api-mcp/<version>) and to the /health response, which leaves the
version out otherwise.
A note on auth: no environment variable is baked into the image and none is
required for the container to start. In HTTP mode clients authenticate per
request with Authorization: Bearer sugra_..., so SUGRA_API_KEY on the
container is only a fallback for requests without a Bearer token.
Your Sugra API key (sugra_...). Required for data tools; catalog tools work without it. Free key: https://app.sugra.ai/settings/billing (50 req/day). Only env var needed for local installs and directory sandboxes.
