Sugra MCP
Server Details
Connect AI agents to primary sources - markets, macro, news, earth, network, entities and research.
- Status
- Healthy
- Uptime
- 100.0% over the last 24 hours
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-11-25
- URL
- Repository
- Sugra-Systems/sugra-api-mcp
- GitHub Stars
- 4
- Server Listing
- Sugra API MCP
- ChatGPT
- –
- Claude
- Sugra API
TDQS
Scored across 11 tools
Most tools target distinct stages (discovery, description, invocation, entity resolution, compliance), and descriptions explicitly guide selection. However, fetch_data overlaps with the search_endpoints+describe_endpoint+call_endpoint pipeline, and resolve_entity vs sugra_entity_lookup/screen sit close together, though the text carefully draws the lines (market data vs KYB/sanctions).
Nine tools follow a clean verb_noun snake_case pattern (call_endpoint, get_snapshot, list_sources, search_endpoints, resolve_entity, etc.). The two compliance tools (sugra_entity_lookup, sugra_entity_screen) deviate with a 'sugra_' prefix and noun_verb form, a minor inconsistency but still readable.
11 tools is well within the ideal range for a data-gateway server, and each earns its place by covering a distinct layer (catalog browsing, search, describe, invoke, entity resolution, composed views, compliance screening).
The surface covers the full loop from discovery (search/list) through description and invocation, plus entity resolution and compliance screening. Gaps are minor, e.g. no dedicated pagination/bulk-enumeration helper or catalog-wide listing, but agents can work around these via search_endpoints and filters.
Available Tools
11 toolscall_endpointARead-onlyIdempotentInspect
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.
Inputs: operation_id (required), body, limit, fields, +2 more. Returns: object
describe_endpointARead-onlyIdempotentInspect
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.
Inputs: operation_id (required). Returns: object
fetch_dataARead-onlyIdempotentInspect
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:
Search the bundled catalog for the query. Top match wins.
If the matched endpoint has required parameters and they are all provided in
params, call it and return the response.If required parameters are missing, return the candidate endpoints and the missing-params list so the LLM can retry with the correct
paramsdict on the next call.If the query names a country and the match takes a
countryorcountriesparam thatparamsleaves unset, return needs_params for it with query_countries (ISO2) instead of running the match without that filter.
Examples:
fetch_data("US CPI inflation", params={"series_id": "CPIAUCSL"})runs fred_series_series_id (/api/v1/fred/series/CPIAUCSL) and returns observations.fetch_data("Bitcoin price")runs onchain_bitcoin_price, which takes no params.fetch_data("Latest financial news")runs news_latest, which has no required params. Only the top match runs, and a param it does not declare returns error unknown_parameters. For one coin's price, name the operation:call_endpoint("crypto_coin_id_price", params={"coin_id": "bitcoin"}).
Inputs: query (required), body, limit, fields, +2 more. Returns: object
get_snapshotARead-onlyIdempotentInspect
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); for macro_calendar, entity is accepted but does not filter the calendar.
Args: recipe: Recipe name from the fixed manifest. entity: Entity dict from resolve_entity ({"namespace": ..., "ids": ...}).
Inputs: entity (required), recipe (required). Returns: object
get_timeseriesARead-onlyIdempotentInspect
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.
Read the step from served_granularity, not granularity. The
latter echoes the request; the former is the step the source built the
points at, and the two can differ (a long price range can come back as
monthly bars under a "1d" request). It reads mixed when the points do
not share one step, unknown when the source does not say, and null
when no point came back. It describes how each point was built, not how
far apart the returned points are: a thinned daily series still reads
1d, and downsampled is what says points were dropped.
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).
Inputs: entity (required), metric (required), max_points, granularity. Returns: object
list_sourcesARead-onlyIdempotentInspect
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.
Inputs: no named parameters. Returns: object
list_toolsetsARead-onlyIdempotentInspect
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.
Inputs: no named parameters. Returns: object
resolve_entityARead-onlyIdempotentInspect
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.
Inputs: query (required), type_hint. Returns: object
search_endpointsARead-onlyIdempotentInspect
Search the bundled Sugra endpoint catalog by natural-language query.
Use this to pick an operation_id. It does not fetch data. Typical loop:
search_endpoints(query) -> ranked hits with required_parameters
describe_endpoint(operation_id) -> params, request_body_schema, agent_hints
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")
Inputs: query (required), limit, source, toolset. Returns: object
sugra_entity_lookupARead-onlyIdempotentInspect
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.
Inputs: value (required), anchor (required), include. Returns: object
sugra_entity_screenARead-onlyIdempotentInspect
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.
Inputs: name (required), dob, country, nationality. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Evidence-backed capital-change intelligence and sourced financial data for AI agents
Structured, cited, real-world data from 300+ sources and the open web for your AI agents.
Licensed, cited financial data for AI agents: news, filings, transcripts, research and tearsheets.
Private company data, entity-resolved news, targeted lists, and alternative signals for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search sourced company, market, and economic data, run read-only SQL, and return cited answers, charts, or reports across earnings calls, filings, central-bank communications, satellite data, shipping, trade, and official statistics.20MIT
- FlicenseNot gradedqualityBmaintenanceConnects AI agents to real-time market data, options analysis, broker order staging, and automated alerts and workflows.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access real-time financial data including crypto, equities, on-chain, prediction markets, and macro via a single API key.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access and synthesize per-ticker financial research data from multiple providers within a private, self-hosted workspace.11 npmMIT
Glama MCP Gateway
Add one secure layer between your agents and this server.