API documentation

MCP

Stonewake serves a Model Context Protocol (MCP) endpoint, so AI assistants and agents can read your workspace directly: ask about the portfolio, one counterparty's risk, or how a score is produced, and the assistant calls the tools below itself.

text
Endpoint: https://mcp.stonewake.ai/

The endpoint speaks MCP over streamable HTTP. Every request is self-contained: there is no session to open and nothing to keep alive, so hosted assistants and local clients connect the same way.

Authentication

The same API keys authenticate MCP and the REST API: send your swk_live_ key as a Bearer token on every MCP request (see Authentication). Two things work without a key: listing the tools, and the documentation search tool. Every tool that reads workspace data requires one.

MCP calls count against the same per-key rate limit and workspace daily quota as direct API calls; see Errors and rate limits.

The tools

Fifteen read-only tools. All but search_stonewake_docs read workspace data and require a key.

Portfolio and scoring

  • portfolio_overview: status counts across the monitored book, the active exposure count, and recent status changes; pass transitions_since to also list the individual transitions since a moment.
  • portfolio_book: the monitored book itself, one row per exposure with its status, score, and top signals with citations, most severe first; paged, and include_inactive adds exposures no longer actively monitored.
  • entity_risk_profile: your team's current risk view of one company by its node_id, with every scored or abstained signal and its citations.
  • scoring_rubric: the scoring configuration behind your team's status bands and scores, plus the team's stored rubric versions.

Company

  • search_companies: find a company by name or identifier (an LEI, a registration number, or scheme:value); hits carry the node_id that the other company tools take. Companies only, never persons.
  • company_profile: one counterparty's identity row from the Stonewake registry of named market participants (export credit agencies, banks, sponsors), by entity_id.
  • company_financials: every filed financial figure for one company, newest reporting period first, each figure citing its register record; a missing period means nothing was filed, not zero.
  • company_events: the register event feed of one company, grouped into display rows by significance; related events fold into one rollup row whose group_key expands it.
  • company_financing: the debt surface of one company: registered charges with bound lenders, listed debt instruments, filed debt positions, derived aggregates, and a maturity wall whose slices expand by bucket.
  • ownership_chain: the upward ownership chains of one company, composed across registers and cited hop by hop; threshold (default 25 percent) and max_depth (maximum 8) bound the walk.

Intelligence

  • screening_lookup: adverse media screenings for your team, over organizations and countries: a filterable list, or one run in full by screening_id with verdicts, findings, and sources.
  • deal_book: your team's export finance deal book: a list ordered by ranking window first, filterable (the rows a desk holds back by default are off the page unless include_hidden is true), each row carrying its window, band word, confirmed state, stated event date, whether your own bank is in, angle and ask; or one deal in full by deal_id with parties, cited timeline, memo, and economics.
  • country_profile: country intelligence: the index of covered countries, or one country in depth by iso3 with its cited risk breakdown, memberships, and your team's deals there.
  • developments: dated, cited developments from your team's research runs: a paged feed, or one whole run by run_id with its grounded findings, quotes, and sources.

Documentation

  • search_stonewake_docs: search this documentation; the one tool that needs no API key.

Two id spaces cross these tools: search_companies hits carry the graph node_id that entity_risk_profile, company_financials, company_events, company_financing, and ownership_chain take, while company_profile takes an entity_id from the separate registry id space. An id from the wrong space answers not_found.

Connect Claude

In Claude, add a custom connector with the endpoint URL https://mcp.stonewake.ai/ and your API key. From Claude Code:

bash
claude mcp add --transport http stonewake https://mcp.stonewake.ai/ \
  --header "Authorization: Bearer $STONEWAKE_API_KEY"

Connect Cursor

Add the server to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects:

json
{
  "mcpServers": {
    "stonewake": {
      "url": "https://mcp.stonewake.ai/",
      "headers": {
        "Authorization": "Bearer swk_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

The key above is a placeholder; use your own.

Other MCP clients

Any MCP client that speaks streamable HTTP can connect: point it at https://mcp.stonewake.ai/ and have it send Authorization: Bearer <key> on every request. Clients on older MCP revisions that open with initialize are answered compatibly. Nothing else is required: no session id, no local process, no package to install.

A first probe from the command line (the tool listing needs no key):

bash
curl -s https://mcp.stonewake.ai/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Calling a tool is one more JSON-RPC request: tools/call with params naming the tool and its arguments. With a key, this reads your portfolio summary:

bash
curl -s https://mcp.stonewake.ai/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer swk_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"portfolio_overview","arguments":{}}}'

The key above is a placeholder; use your own.

Errors

  • A tool call whose key is missing or refused answers a JSON-RPC error with the stable code -32001 and a message pointing at Authentication. The message says when no credential was sent at all; a credential that was sent and refused receives one uniform message that, like the API's 401, does not say why.
  • Failures of the tool run itself (a 403, 404, or 429 from the API, or the API being unreachable) come back as tool results with isError true and a machine-readable JSON body, so an agent can react. A rate-limited result carries retry_after_seconds for backoff.
  • Tool responses wrap Stonewake data between STONEWAKE_DATA markers, and the response says so: text inside the markers is data, not instructions for the model.

Posture

Connecting an assistant does not widen the surface. The tools are read-only views over the same workspace data as the REST API, the companies-and-countries-only rule applies unchanged, and the Security and Terms of use pages cover MCP access exactly as they cover the API.