Connected Agents (MCP)

Connected Agents let AI assistants read Cleotic project evidence through the Model Context Protocol (MCP). Use this when you want an agent client to answer questions about your projects, segments, visibility, share of voice, citations, responses, and reports without exporting data by hand.

Cleotic MCP access is read-only. Agents can inspect authorised data, but they cannot create projects, change setup, edit reports, or mutate your account.

What you can connect

Use any agent client that supports remote MCP over Streamable HTTP and bearer-token authentication. OAuth is the preferred connection path. Scoped MCP API keys are available as an alternative route for clients that cannot complete OAuth yet.

The MCP endpoint is shown in Settings -> Connected Agents:

https://api.cleotic.ai/api/v2/mcp

Before you start

You need:

A Cleotic account with access to the organisation you want the agent to use
Accepted Cleotic terms for normal authenticated access
An MCP-capable agent client
Admin or member access to the projects the agent should read

One MCP connection is scoped to the selected organisation. If you work across multiple organisations, create or authorise a separate connection for each one.

Connect an agent client

Use OAuth when your agent client supports it:

In Cleotic, open Settings -> Connected Agents.
Copy the Cleotic MCP endpoint.
In your agent client, add a remote MCP server using that endpoint.
Choose OAuth or browser sign-in when the client asks how to authenticate.
Sign in to Cleotic in the browser and select the organisation you want the agent to read.
Approve the client connection.

OAuth uses WorkOS/AuthKit discovery from the MCP endpoint. After authorisation, the client discovers only the tools allowed by your current Cleotic organisation and project permissions.

Scopes

OAuth connections inherit the signed-in user's current Cleotic organisation and project access. For MCP API keys, choose the smallest set of scopes the agent needs:

Scope	Allows the agent to read
`mcp.projects.read`	Project setup, brands, segments, prompts, and selector details
`mcp.analytics.read`	Visibility, share of voice, answer gaps, perception, and source health
`mcp.evidence.read`	Responses, citations, saved reports, and linked source context
`mcp.account.read`	Plan, usage, capacity, and capability information
`mcp.docs.read`	Public Cleotic docs. Docs tools are available to authenticated MCP sessions.

If an MCP API key scope is missing, Cleotic either hides the related tool from discovery or returns a structured missing-scope error for that tool call.

Available tools

The exact tool list depends on the signed-in user's access for OAuth connections, or the selected key scopes for MCP API keys.

Documentation

search_docs
get_doc

Projects and setup

list_projects
get_project_overview
list_segments
list_prompts
get_portfolio_summary

Analytics

get_visibility
get_share_of_voice
get_answer_gaps
get_perception_summary
get_source_health

Evidence

list_responses
get_response
list_citations
get_citation
list_reports
get_report

Account

get_plan_usage

Cleotic also exposes guided prompts such as a project health brief and an evidence drill-down when the connection has the required scopes.

Suggested first prompts

After connecting, try:

"List my Cleotic projects and summarise which one needs attention first."
"Give me a health brief for the project named Acme."
"For Acme, compare visibility and share of voice over the last 30 days."
"Find answer gaps where competitors appear and my brand does not."
"Pull supporting response and citation IDs for the strongest recommendation."

Ask the agent to cite Cleotic response, citation, or report IDs when it makes evidence-backed claims.

Manage and revoke keys

Open Settings -> Connected Agents to review active MCP keys. Revoke a key when:

A teammate leaves the organisation
A laptop, server, or agent client is retired
A secret may have been pasted somewhere unsafe
The client no longer needs Cleotic access

Revoking a key stops future MCP requests that use it. OAuth connections follow the connected user's current Cleotic permissions.

Troubleshooting

Check that the endpoint is https://api.cleotic.ai/api/v2/mcp and that the client is configured for remote MCP over Streamable HTTP.

For OpenClaw, set the server transport explicitly:

{
  "url": "https://api.cleotic.ai/api/v2/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer <cl_mcp_...>"
  }
}

If the transport is omitted, OpenClaw defaults to SSE and may report Streaming is disabled on this server.