Sugra API MCP
OfficialThis MCP server gives read-only access to Sugra’s data catalog and APIs, letting agents discover, inspect, and call 1,600+ endpoints across markets, macro, news, earth, network, entities, and research.
Search the endpoint catalog by natural-language query and filter by toolset or source.
Describe endpoints to get exact parameters, request-body schemas, timing/cost hints, and examples.
Call any endpoint by operation_id with params/body, field projection, record limits, and optional raw payloads.
Fetch data in one step from a plain-language request by auto-selecting the best endpoint.
List available toolsets and source families with endpoint counts.
Screen people or organizations against sanctions/PEP/adverse-media data as a compact review signal.
Look up entities by LEI or VAT number and return a compact KYB envelope with optional ownership/adverse-media slices.
Use OAuth2-protected, read-only, idempotent tools suitable for agent data retrieval.
Integrates Google Gemini with Sugra API for retrieving market prices, macro indicators, and entity screening data.
Supports JetBrains IDEs (via Gemini Code Assist) to use Sugra API tools for financial data and entity lookup within the development environment.
Allows OpenAI GPT models to fetch market data, screen entities, and access financial endpoints via Sugra API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Sugra API MCP What is the current price of Apple stock?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Sugra MCP is built and run by Sugra Systems, Inc. It brings Sugra Data into AI assistants and agents over the Model Context Protocol: 1,600+ endpoints from 200 primary sources across 36 data domains - central banks, national statistics offices, regulators, intergovernmental bodies and more. The agent searches the catalog, reads an endpoint's description and calls it, and every answer carries its source and date.
Published in Anthropic's Connectors Directory, the OpenAI Plugins Directory and the GitHub MCP Registry. Works with Claude, Claude Code, ChatGPT, Codex, Grok, Cursor, Antigravity, GitHub Copilot, VS Code, Zed, Cline, Continue and any MCP client.
Watch: How Sugra MCP works · Seven directions, one key
Seven directions
Direction | What an agent can ask for | Learn more |
Sugra Finance | Quotes, price history, company financials, SEC filings, funds, options, futures and Treasuries | |
Sugra Macro | Inflation, GDP, interest rates, jobs, trade and public finance of whole countries | |
Sugra News | Headlines, feeds and the world's media attention | |
Sugra Earth | Weather, climate, air quality, energy, natural hazards and vessel traffic | |
Sugra NetAtlas | IP and ASN lookups, routing history, geolocation and internet outages | |
Sugra Entity | Legal entity identifiers, company registries, sanctions and PEP screening | |
Sugra Research | Papers, preprints, citations and authors |
Related MCP server: @prism/mcp-server
Install
The server is hosted, so there is nothing to run. Add Sugra from your agent's directory or install the sugra-api-skills plugin, then connect as shown below. The plugin also carries the Sugra API Skills, which give the agent the procedure - find an operation, read the response, cite the source.
Claude (claude.ai, Desktop, mobile and Cowork): Add to Claude opens Sugra in Anthropic's Connectors Directory.
Claude Code, the plugin with the skills and the server:
/plugin marketplace add Sugra-Systems/sugra-api-plugins
/plugin install sugra-api-skills@sugra-api-pluginsAdd to ChatGPT opens Sugra in the OpenAI Plugins Directory, which serves both ChatGPT and Codex. In ChatGPT the skills install together with the server.
Codex, the skills plugin:
codex plugin marketplace add Sugra-Systems/sugra-api-plugins
codex plugin add sugra-api-skills@sugra-api-pluginsGitHub MCP Registry opens Sugra in GitHub's registry. Its Install MCP server button adds the server to VS Code, VS Code Insiders or the GitHub Copilot app.
GitHub Copilot CLI, the plugin with the skills and the server:
copilot plugin marketplace add Sugra-Systems/sugra-api-plugins
copilot plugin install sugra-api-skills@sugra-api-pluginsVS Code: Install in VS Code adds the server.
Grok, the plugin with the skills and the server:
grok plugin install Sugra-Systems/sugra-api-plugins#xaiCursor: Install in Cursor adds the server. The plugin with the skills and the server:
git clone https://github.com/Sugra-Systems/sugra-api-plugins
mkdir -p ~/.cursor/plugins/local
cp -R sugra-api-plugins/cursor ~/.cursor/plugins/local/sugra-api-skillsThe skills plugin:
git clone https://github.com/Sugra-Systems/sugra-api-plugins
agy plugin install ./sugra-api-plugins/antigravityAntigravity does not start the server from the plugin: add it as shown under Connect.
The skills, for any agent that reads Agent Skills:
npx skills add https://mcp.sugra.aiThe server: add it as shown under Connect.
Run it locally
The PyPI package runs the server on your machine over stdio with an API key. Python 3.13 or newer:
pip install sugra-api-mcp
export SUGRA_API_KEY=sugra_... # free key: https://app.sugra.ai/register
sugra-api-mcp call quotes_symbol_price --params '{"symbol":"AAPL"}'Connect
Every client connects to one address. Sign in with your Sugra account, or send an API key as Authorization: Bearer <key>:
https://mcp.sugra.ai/mcpClaude: connect Sugra in the directory and sign in with your Sugra account. Added Sugra earlier as a custom connector? Remove that one before you connect from the directory, or you will have two.
Claude Code signed in with a claude.ai account picks the connector up on its own. With the plugin, sign in to its server from /mcp.
In ChatGPT or Codex, connect Sugra and sign in with your Sugra account.
GitHub Copilot CLI, by hand:
copilot mcp add --transport http sugra-api https://mcp.sugra.ai/mcpVS Code, by hand, .vscode/mcp.json:
{ "servers": { "sugra": { "type": "http", "url": "https://mcp.sugra.ai/mcp" } } }Both open the Sugra sign-in page in your browser the first time they connect.
Grok connects through the plugin.
Cursor, by hand, ~/.cursor/mcp.json:
{ "mcpServers": { "sugra": { "url": "https://mcp.sugra.ai/mcp" } } }To sign in, open Cursor Settings, then Tools & MCPs, and select Connect next to sugra.
agy mcp add sugra-api https://mcp.sugra.ai/mcpThe CLI, the app and the IDE share the server. Antigravity opens the Sugra sign-in page the first time the agent uses it.
Add the address above as a remote MCP server in any client that speaks Streamable HTTP.
{
"mcpServers": {
"sugra": {
"command": "sugra-api-mcp",
"env": { "SUGRA_API_KEY": "sugra_..." }
}
}
}Claude Desktop reads it from claude_desktop_config.json, Cursor from ~/.cursor/mcp.json. Other stdio clients take the same command and environment variable in their own MCP settings.
Tools
Tool | What it does |
| Finds the best endpoint for a plain-language request and calls it, in one step |
| Searches the catalog of 1,600+ endpoints |
| Shows an endpoint's parameters, required inputs and cost hints |
| Calls an endpoint by its operation id, with optional |
| Lists the catalog groups with their endpoint counts |
| Lists the sources behind the catalog |
| Screens a name against sanctions lists and watchlists |
| Looks up a company by LEI or VAT number, with screening |
| Hosted only: turns a ticker, company, indicator, coin or currency pair into one entity |
| Hosted only: one current view of an entity, with freshness and provenance |
| Hosted only: a bounded series of an entity's price or macro metric |
The server also ships six workflow prompts (market snapshot, macro briefing, sanctions screening, sector comparison, earth conditions, source overview) and serves five of the Sugra API Skills as MCP resources under sugra://skills/.
Documentation
Self-hosting - running your own HTTP server
Blog
Development
git clone https://github.com/Sugra-Systems/sugra-api-mcp
cd sugra-api-mcp
pip install -e ".[dev,http]"
pytestThe test matrix runs on Python 3.13, 3.14 and 3.15.
Help
Email: support@sugra.systems
Reporting a vulnerability: SECURITY.md
License
MIT © 2026 Sugra Systems, Inc.
Available Tools
8 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
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
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…
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.
Maintenance
Related MCP Connectors
Unified financial infrastructure connecting AI agents directly to trade live/demo brokerage accounts, Web3 non-custodial wallets, real-time market data across equities, ETFs, crypto, forex, options, DeFi swaps, and prediction markets, institutional research feeds, and algorithmic strategy backtesters.
Pay-per-call APIs for trading agents: market data, indicators, insider trades, on-chain tools.
Real-time data API for AI Agents: stocks, weather, forex, logistics, search, scrape, news, IP.
Pay-per-call data for AI agents: BTC price, airport delays, weather, SEC filings, paid-API routing
Related MCP Servers
AlicenseBqualityBmaintenanceUS/HK markets — 110 tools: real-time quotes, options, orders, fundamentals, alerts, DCA & portfolio19316Apache 2.0- 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 gradedqualityDmaintenanceProvides live data API for AI agents with 51 REST endpoints across finance, travel, weather, news, and more, using USDC micropayments without API keys.42 npmMIT
- AlicenseAqualityCmaintenanceProvides curated US economic data from Treasury, FRED, BLS, BEA, and other sources through an MCP interface. Enables querying economic series, fetching data with provenance tracking, and accessing cached artifacts.9MIT