MCP server
Connect Claude, Cursor, or another AI client to your Elmo instance.
Every Elmo instance serves a Model Context Protocol endpoint, so an AI client can read your visibility data and manage prompts without you copying numbers between windows.
https://<your-instance>/api/mcpConnect
Sign in from the client
Most clients can authenticate themselves — give them the URL and they will open a browser for you to sign in.
claude mcp add --transport http elmo https://<your-instance>/api/mcpIn a client that takes JSON instead:
{
"mcpServers": {
"elmo": { "type": "http", "url": "https://<your-instance>/api/mcp" }
}
}The connection then acts as you, in the workspaces you belong to.
Or use an API key
For a client that can't open a browser — a container, a scheduled job — issue a key under Settings → API keys and send it as a bearer token:
{
"mcpServers": {
"elmo": {
"type": "http",
"url": "https://<your-instance>/api/mcp",
"headers": { "Authorization": "Bearer elmo_..." }
}
}
}A key is also how you grant less than your own access: tick only the scopes you want, and optionally narrow it to specific brands.
A connection is only offered the tools its scopes allow, and not every scope maps to a tool:
| Scope | MCP tool |
|---|---|
brands:read | whoami, list_models, list_brands, get_brand, list_competitors |
prompts:read | list_prompts, list_prompt_tags |
prompts:write | create_prompts, update_prompt |
billing:read | get_billing |
analytics:read | get_analytics, get_prompt_performance, get_citations, get_query_fanout, get_opportunities |
runs:read | list_runs, get_run |
competitors:write and competitors:delete matter to the REST API only — MCP can
read competitors but never changes them, like everything else it touches. A key holding just one of
them reaches no MCP tool beyond what its other scopes already grant.
Check it works
Ask the assistant to run whoami. It will report what the connection is, which workspaces it reaches,
and every tool it may call — which is the quickest way to see why something else was refused.
Then try:
Which of my brands has the lowest visibility this month, and what are the models citing instead?
Notes
- The connection only ever gets the tools its permissions allow, so a client is never offered something it would then be refused.
- It can create and edit prompts, but nothing deletes data and nothing changes billing.
- Self-hosting: no extra configuration, but
APP_URLmust be the address clients actually reach you on — that is what the sign-in flow is advertised from, and what the tokens it issues are bound to. It has to be an HTTPS URL, orlocalhost; the app refuses to start otherwise, because a token bound to anything else is one no MCP client will accept.
Was this page helpful?