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.
- 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.
- 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.
- 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.
https://<YOUR_MCP_ENDPOINT>/mcp- Transport
- Streamable HTTP
- Authentication
- Bearer token · dedicated MCP key
- Header
Authorization: Bearer <YOUR_MCP_KEY>- Agent guide
- https://refracto.ai/mcp/agent.md
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.
get_contextIdentify the tenant, available languages, features and effective limits.
searchFind a story in the published archive. Keep its slug for the next call.
read_briefingRead the briefing and its sources. Use analyze_briefing to inspect the existing evidence.
| Tools | What your agent can do |
|---|---|
get_context | Read tenant identity, languages, enabled features and limits. |
get_frontmost_read | Explore ranked and most-read live coverage. |
list_briefingsread_briefingrelated_briefings | Browse the archive, read full briefings and follow related coverage. |
searchsearch_semanticsearch_source | Search by keywords, meaning or a publisher article URL. |
analyze_briefing | Inspect existing divergence, sentiment, geography and source attribution. |
list_sectorslist_languagesget_stats | Understand the catalogue and available publication statistics. |
get_mapread_place | Explore geographical coverage and stories at a returned place. |
list_clustersread_clusterbriefing_cluster | Inspect the sources and original article metadata behind live briefings. |
list_audiobriefing_audioread_audio | Find current audio and obtain an authorized, short-lived download URL. |
list_socialbriefing_socialread_social_media | Inspect 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.
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