Connect your agent to your demand data
Point Claude, Cursor, or any MCP-capable agent at the Recommend MCP server. It reads the same demand data your dashboard runs on — every project, scope and tracked object — read-only in v1.
One address, one header
https://data-api.recommend.studio/mcp- Transport
- Remote · Streamable HTTP
- Authentication
- OAuth or API key
- Access
- Read-only · v1
How you authenticate
Connect from your MCP client in one click — OAuth 2.1 with dynamic registration. No key to copy; you grant access and revoke it any time from Connected applications.
Send your key in an X-Api-Key header. The key resolves your client, so every tool acts on your data and nobody else's.
Point a client at the server with no credential and it can discover what's there — the handshake and the list endpoints. Calling any tool needs OAuth or an API key.
- initialize
- tools/list
- resources/list
- prompts/list
One connection per client
An agency can run several clients from one account — each stays isolated behind its own connection.
Your login. One OAuth sign-in.
One connector each, pinned when you sign in.
Each client's own view, markets and tracked objects.
One connector, one client
When you connect, you choose the client. That connection only ever sees that client's data — nothing leaks across.
A connector per client
Running five clients? Add five connectors from your dashboard, each with its own URL. Switch by toggling the one you need in your agent.
Projects within a client
A client can hold several projects — a default and focused ones. Tools run against the project you name, or the default.
Add it to your agent
Connect from your client's connector directory in one click, or add the server by hand. Pick your agent below.
Connect from a directory
The one-click path — no config to paste, OAuth on first connect.
Open your client's connector directory and add Recommend.
Sign in, pick the client, and approve read-only access.
The tools appear in your client — ask your first question.
- describe_project
- whats_top
- explain
- list_sources
- check_demand
Add it manually
Connect with a custom connector.
- Navigate to Settings → Connectors.
- Click the + button next to Connectors and select Add custom connector.
- Enter the connector's name and the MCP server URL:Name:
Recommendhttps://data-api.recommend.studio/mcp - Click Add, then open the connector and click Connect to authorize via OAuth.
- To enable Recommend in a conversation, click + in the chat, hover over Connectors, and toggle it on.
What next?
When connected, ask your agent:
Describe my projects, then show what's gaining demand in my main market.Ask for the evidence behind any ranking — it cites the sources it read.
What this server declares
An MCP client can use four kinds of capability here: tools it calls, resources it can read, prompt templates it can run, and a logging stream it can follow.
The callable functions your agent invokes to get work done — 5 read-only tools in v1. Each answers one specific question about your demand data, takes typed parameters, and returns structured JSON your agent can reason over and chain into the next call. The full catalogue, grouped by the questions people actually ask, is in the next section.
See all five tools, grouped by intent, in the next section.
Read-only data the server publishes at stable URIs, so an agent can pull it — or subscribe to it — directly, rather than spending a tool call. Point a client at a demand:// URI and it reads a project's ranked objects or its scopes, and is notified when they change: no polling, no wasted context.
{
"resources": [
{
"uri": "demand://eurovilla/default/objects",
"name": "Eurovilla — tracked objects",
"description": "Ranked demand cards for the default project",
"mimeType": "application/json"
},
{
"uri": "demand://eurovilla/default/scopes",
"name": "Eurovilla — scopes",
"mimeType": "application/json"
}
]
}Reusable, server-authored prompt templates a client can run instead of free-typing. Each template names its arguments and expands into a vetted workflow — so “this week's demand brief for Croatia” runs the same, correct way every time, whichever agent asks and whoever is driving it.
{
"prompts": [
{
"name": "weekly-demand-brief",
"description": "Summarise the week's demand movers for one market",
"arguments": [
{ "name": "market", "description": "e.g. hr", "required": true },
{ "name": "project", "description": "Project slug", "required": false }
]
}
]
}Structured log lines the server streams back while a call runs — which tool is executing, how many documents it scored, how long it took. Your agent (and you) can follow progress in real time and trace exactly what happened, instead of waiting on a silent request and guessing when it stalls.
{
"jsonrpc": "2.0",
"method": "notifications/message",
"params": {
"level": "info",
"logger": "check_demand",
"data": "scored ‘padel’ against 1,204 documents in 380ms"
}
}What your agent can do
Five read-only tools, grouped by the questions your agent actually asks — orient itself, justify a ranking with evidence, and look up anything beyond what you already track.
What's happening?
describe_projectDescribe projectReadExplain what a client tracks and its baseline metrics — the scopes, the tracked objects and how the project is set up. The orientation step: call it before any ranking so the agent knows what “top” is being measured against.
- project
- stringoptional— Project slug. Omit for the default project.
{ project, view, markets[], scopes[], objects: n, baseline }whats_topWhat's topReadRank the strongest, weakest or riskiest categories in a project for a market — the core ranking read behind most questions. Choose the axis with `by`; the agent gets an ordered list it can reason over.
- by
- stringoptional— strongest | weakest | riskiest. Defaults to strongest.
- market
- stringoptional— e.g. hr. Defaults to the project's primary market.
- project
- stringoptional— Project slug. Omit for the default project.
- limit
- integeroptional— How many to return. Defaults to 10.
[ { name, score, momentum, rank } ]How do you know?
explainExplain a scoreReadReturn the evidence behind a score: the references, the reasoning, the source tier and the score composition. A plausible ranking any model can produce from the open web — handing over the evidence behind it, inside the same conversation, is the part that can't be reproduced by prompting.
- id
- stringrequired— The object to explain (from whats_top).
- market
- stringoptional— e.g. hr.
- project
- stringoptional— Project slug. Omit for the default project.
{ id, score, composition, reasoning, references[], source_tiers[] }list_sourcesList sourcesReadDiscover where a project's signal comes from — the feeds and queries the workers read to build demand, each with its provenance and tier. Use it to audit or defend a read.
- project
- stringoptional— Project slug. Omit for the default project.
[ { id, name, engine, url | keywords, tier } ]What about X?
check_demandCheck demandReadRate-limitedScore any brand or term outside current tracking — fetched live from external data and scored on the fly. Carries a real per-call cost, so it sits behind its own permission and rate limit. Its usage log also reveals a ranked list of what customers wish was tracked.
- term
- stringrequired— The brand or term to score, in plain language.
- market
- stringoptional— e.g. hr.
- project
- stringoptional— Project slug. Omit for the default project.
{ term, score, momentum, signals, trend[], sources[] }Read-only in v1
Version one ships without write tools — an agent can read and reason over your demand data, but not change what gets tracked. Writes are designed and deferred; when they arrive they sit behind their own scope and your explicit consent.
First thing to ask
Once connected, try this.
List my projects, then show the ten objects with the strongest demand in my main market.
curl -s -X POST https://data-api.recommend.studio/mcp \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <your-mcp-key>' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"whats_top","arguments":{}}}'