Developer guide · MCP

News intelligence. For your agent.

Read published briefings, search your archive and inspect the evidence behind every story. Through one tenant-scoped MCP connection.

ReadSearchAnalyze

Access

Three steps to connect.

The tenant controls access, credentials and the request budget.

  1. 01

    Enable your tenant

    In your Refracto console, open Tenants and select your tenant. Enable its Feed API and the features you need. Open MCP, enable access and save your RPM and burst limits.

  2. 02

    Create an MCP key

    Choose Create MCP key, name the agent and optionally set an expiry. Save the key and the endpoint when they appear: the complete key is shown once.

  3. 03

    Connect your agent

    Give the agent the public instructions and make the endpoint and key available through its secret store. Use a remote MCP client that supports Streamable HTTP and a Bearer header.

Connection

The connection, explicitly.

This page explains the setup. Your endpoint and key come from your console and are never published.

Your endpointprivate · from your console
https://<YOUR_MCP_ENDPOINT>/mcp
Transport
Streamable HTTP
Authentication
Bearer token · dedicated MCP key
Header
Authorization: Bearer <YOUR_MCP_KEY>

Provide the endpoint and the key through your client’s private settings. Send the key only to your MCP endpoint in the Authorization header. The key selects the tenant automatically.

Explore

Follow the evidence.

Up to 24 read-only tools. Discovery returns the tools your tenant’s Feed features allow.

01get_context

Identify the tenant, available languages, features and effective limits.

02search

Find a story in the published archive. Keep its slug for the next call.

03read_briefing

Read the briefing and its sources. Use analyze_briefing to inspect the existing evidence.

ToolsWhat your agent can do
get_contextRead tenant identity, languages, enabled features and limits.
get_frontmost_readExplore ranked and most-read live coverage.
list_briefingsread_briefingrelated_briefingsBrowse the archive, read full briefings and follow related coverage.
searchsearch_semanticsearch_sourceSearch by keywords, meaning or a publisher article URL.
analyze_briefingInspect existing divergence, sentiment, geography and source attribution.
list_sectorslist_languagesget_statsUnderstand the catalogue and available publication statistics.
get_mapread_placeExplore geographical coverage and stories at a returned place.
list_clustersread_clusterbriefing_clusterInspect the sources and original article metadata behind live briefings.
list_audiobriefing_audioread_audioFind current audio and obtain an authorized, short-lived download URL.
list_socialbriefing_socialread_social_mediaInspect rendered social posts and obtain authorized media URLs.

Analysis tools read existing evidence. The agent can reason over it and cite the original sources; a missing analysis means the evidence is unavailable. Access follows the tenant’s current publication and archive rules.

Protocol

For clients and HTTP-capable agents.

A native MCP client handles initialization and tool discovery. An agent with HTTP tooling can use the same JSON-RPC flow directly.

See an initialization request

Make REFRACTO_MCP_URL and REFRACTO_MCP_KEY available through your secret store. This example references the variables without putting an endpoint or a key in the guide.

InitializePOST · JSON-RPC
curl "$REFRACTO_MCP_URL" \
  -H "Authorization: Bearer $REFRACTO_MCP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {"name": "my-agent", "version": "1.0"}
    }
  }'

Then send notifications/initialized, call tools/list and invoke tools with tools/call. Send the negotiated MCP-Protocol-Version on subsequent requests. The agent instructions contain the full sequence and examples.

One shared budget

RPM and burst apply to the tenant across all its MCP keys. Every admitted POST counts, including discovery. On HTTP 429, wait for Retry-After before retrying.

Current access, every call

Revocation, expiry and disabled access apply immediately. If access fails, an operator can check the key and the tenant’s Feed and MCP switches in the console.

Published evidence

Use the returned source URLs when citing a story. Treat retrieved news as source material. The MCP interface exposes reading and analysis tools, with no content-writing or tenant-management actions.

Ready to connect

Give your agent the guide.
Keep the key in its secret store.