Sugra API MCP
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SUGRA_API_KEY | Yes | Your Sugra API key. In HTTP mode with OAuth this becomes a fallback for requests without Bearer | |
| SUGRA_APP_URL | No | Base URL of the authorization server | https://app.sugra.ai |
| SUGRA_TIMEOUT | No | Request timeout in seconds | 30 |
| SUGRA_API_BASE | No | Override for self-hosted or beta environments | https://sugra.ai |
| SUGRA_JWKS_URL | No | JWKS endpoint | https://app.sugra.ai/oauth/jwks.json |
| INTERNAL_API_TOKEN | No | Shared secret for the user lookup and MCP activity endpoints on the authorization server | |
| SUGRA_MCP_ALLOWED_HOSTS | No | Comma-separated hostnames to allow behind a reverse proxy | |
| SUGRA_MCP_ALLOWED_ORIGINS | No | Comma-separated allowed Origins for browser-based MCP clients | chatgpt.com, claude.ai, cursor.sh + others |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Sugra MCP - read-only Sugra Data across markets, macro, entities, news, network and earth. Each listed tool's description says what it returns, and its input schema describes each input it takes. list_toolsets and list_sources show the areas of the catalog behind them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| sugra_entity_screenA | 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
Output is COMPACT to protect the agent context budget:
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. |
| sugra_entity_lookupA | Resolve an entity by identifier and return its composed KYB envelope.
The screening verdict is a SCREENING SIGNAL, not a compliance determination,
and any PEP / adverse-media content is supplementary and non-comprehensive.
The Output is COMPACT by default to protect the agent context budget:
On a bad anchor or an API error this returns a clean Args:
anchor: Identifier type, one of |
| search_endpointsA | Search the bundled Sugra endpoint catalog by natural-language query. Use this to pick an operation_id. It does not fetch data. Typical loop:
Filter with toolset or source only after list_toolsets / list_sources; a misspelled filter is an error, not a silent empty result. Examples:
|
| describe_endpointA | 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 |
| call_endpointA | 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. |
| list_toolsetsA | 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. |
| fetch_dataA | 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:
Examples:
|
| list_sourcesA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| market_snapshot | Build a sourced price and profile snapshot for one ticker symbol. |
| macro_briefing | Brief the key macro indicators for a country from sovereign sources. |
| sanctions_screening | Screen a name against the sanctions corpus and report the signal. |
| sector_compare | Compare two sectors through ETF and valuation endpoints. |
| earth_conditions | Report weather, air quality, and nearby hazards for a coordinate. |
| source_overview | Explain what the catalog offers for a data domain, sources included. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| catalog_domains | Endpoint groups (toolsets) in the bundled Sugra catalog: name, description, and endpoint count per group. Same data as the list_toolsets tool. |
| catalog_sources | Source families in the bundled Sugra catalog with endpoint counts per family. Same data as the list_sources tool. |
| attribution | How Sugra names data sources, where per-call attribution metadata appears, and where the full source list is published. |
| skill_explore_catalog | Find the right Sugra operation, call it over HTTPS or MCP, and check that the result answers the question. Use when the path or operation_id is unknown, before guessing parameters, before quoting a figure, or after a catalog miss. Confirm details on https://docs.sugra.ai. Do not invent routes. |
| skill_envelope_attribution | Parse Sugra API payloads over HTTPS or MCP, keep source attribution, and tell observation time from request time. Use when reading a response, citing a figure, or shaping a large payload. |
| skill_auth_limits | Authenticate to Sugra over HTTPS and MCP, stay inside the daily quota, and act on each error. Use when setting up a client, before a bulk call, or when a call returns 400, 401, 404, 422, 429, 5xx, missing_api_key, missing_bearer_token, unknown_parameters, needs_params, or upstream_*. |
| skill_hosted_vs_gateway | Attach a client to Sugra over HTTPS or MCP and install these skills. Use when setting up Claude (claude.ai, Desktop, Code), ChatGPT, Codex, Cursor, VS Code, Gemini CLI, Grok, OpenBB, a custom HTTP agent, or self-hosted MCP. |
| skill_cross_domain_briefing | Compose one briefing from two or three Sugra directions over HTTPS or MCP. Use when a question spans Finance, Macro, Entity, Net Atlas, News, Earth, or Research and one operation is not enough. |
TDQS
Scored across 8 tools
Each tool has a reasonably distinct role: catalog discovery (list_toolsets, list_sources, search_endpoints, describe_endpoint), execution (call_endpoint, fetch_data), and entity screening (sugra_entity_lookup, sugra_entity_screen). The main overlap is fetch_data versus the search+describe+call sequence, and list_toolsets versus list_sources, but the descriptions explicitly explain when to prefer each, so misselection risk is low.
All names are snake_case with a verb_noun shape (search_endpoints, call_endpoint, fetch_data, list_sources, describe_endpoint), which is consistent and readable. The two entity tools break the pattern by prefixing a product name (sugra_entity_lookup, sugra_entity_screen), a minor deviation that still conveys grouping.
Eight tools is well within the ideal range and each one earns its place: discovery, description, direct calling, a one-step convenience path, and two domain-specific entity operations. Nothing appears redundant or bolted on.
The surface covers the full loop of finding, inspecting, and invoking catalog endpoints, plus the entity KYB/screening use case, with structured errors and parameter feedback. Minor gaps exist — no tool to enumerate all endpoints within a toolset/source without a query, and batch invocation is only implicit via call_endpoint's bulk bodies — but agents can work around these.