# Sugra API (remote · app.sugra.ai)

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

- Trust score: 76/100 (medium)
- Change this week: +10
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `app.sugra.ai`: 76/100 (this document), [markdown](https://verifymcp.io/servers/ai-sugra-api-mcp/app.md), [page](https://verifymcp.io/servers/ai-sugra-api-mcp/app)
- pypi · `sugra-api-mcp`: 13/100, [markdown](https://verifymcp.io/servers/ai-sugra-api-mcp/sugra-api-mcp.md), [page](https://verifymcp.io/servers/ai-sugra-api-mcp/sugra-api-mcp)

## Channel facts

- Endpoint: `https://app.sugra.ai/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.9.1`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 94/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation is enforced on tool calls, advertised via RFC 9728 protected-resource metadata. Discovery is public, which costs nothing: no tool can be invoked without a token.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
  - The authorisation server offers only Dynamic Client Registration (RFC 7591), which MCP 2026-07-28 deprecated in favour of Client ID Metadata Documents.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 59/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 1965 tokens (~178/item across 11 items; 11 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 75/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 13% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http ai-sugra-api-mcp https://app.sugra.ai/mcp
```

### Codex

```toml
[mcp_servers.ai-sugra-api-mcp]
url = "https://app.sugra.ai/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ai-sugra-api-mcp": {
      "type": "remote",
      "url": "https://app.sugra.ai/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add ai-sugra-api-mcp --url https://app.sugra.ai/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  ai-sugra-api-mcp:
    url: "https://app.sugra.ai/mcp"
```

### Other

```json
{
  "mcpServers": {
    "ai-sugra-api-mcp": {
      "type": "http",
      "url": "https://app.sugra.ai/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 76, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-01 (score 75, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 74, +7)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 67, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-28 (score 67, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 66, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 65)

First indexed and scored.

## MCP tools (11)

### `sugra_entity_screen` (~256 tokens)

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.

Input parameters:

- `country`
- `dob`
- `name` (string, required)
- `nationality`

### `sugra_entity_lookup` (~330 tokens)

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.

Input parameters:

- `anchor` (string, required)
- `include`
- `value` (string, required)

### `search_endpoints` (~46 tokens)

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

Input parameters:

- `limit` (integer)
- `query` (string, required)
- `source`
- `toolset`

### `describe_endpoint` (~92 tokens)

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.

Input parameters:

- `operation_id` (string, required)

### `call_endpoint` (~242 tokens)

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.

Input parameters:

- `body`: JSON request body for a POST operation, matching the request_body_schema returned by describe_endpoint(operation_id). Omit for GET operations.
- `fields`
- `include_raw` (boolean)
- `limit`
- `operation_id` (string, required)
- `params`: 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…

### `list_toolsets` (~18 tokens)

List endpoint groups available in the bundled catalog.

### `fetch_data` (~364 tokens)

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.

Input parameters:

- `body`: JSON body for an auto-selected POST operation; the tool returns the request_body_schema to fill when the match needs one.
- `fields`
- `include_raw` (boolean)
- `limit`
- `params`: 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…
- `query` (string, required)

### `list_sources` (~17 tokens)

List endpoint source families derived from catalog metadata.

### `resolve_entity` (~203 tokens)

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.

Input parameters:

- `query` (string, required)
- `type_hint`

### `get_snapshot` (~170 tokens)

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": ...}).

Input parameters:

- `entity` (required)
- `recipe` (string, required)

### `get_timeseries` (~186 tokens)

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).

Input parameters:

- `entity` (required)
- `granularity` (string)
- `max_points` (integer)
- `metric` (string, required)

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/ai-sugra-api-mcp/app#diagnostics

## Score history

- 2026-08-03: 76
- 2026-08-02: 75
- 2026-08-01: 75
- 2026-07-31: 74
- 2026-07-30: 67
- 2026-07-29: 67
- 2026-07-28: 67
- 2026-07-27: 66
- 2026-07-26: 65

## Links

- Remote endpoint: https://app.sugra.ai/mcp
- Repository: https://github.com/Sugra-Systems/sugra-api-mcp
- Changelog RSS feed: https://verifymcp.io/servers/ai-sugra-api-mcp/app/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/ai-sugra-api-mcp/app/changelog.json
- HTML version of this page: https://verifymcp.io/servers/ai-sugra-api-mcp/app