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 with OAuth

Use OAuth when your agent client supports it:

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

After authorisation, the client discovers only the tools allowed by your current Cleotic permissions and granted scopes.

Connect with an MCP API key

Use an MCP API key only when OAuth is not available in your client.

1. In Cleotic, open Settings -> Connected Agents.
2. Click New key.
3. Give the key a name that identifies the client or machine using it.
4. Select the read scopes the client needs.
5. Create the key and copy the secret immediately. Cleotic shows it once.
6. In your agent client, add the Cleotic MCP endpoint and use the key as a bearer token.

MCP keys start with cl_mcp_. Ordinary product API keys and X-API-Key authentication are not accepted by the MCP endpoint.

Scopes

Choose the smallest set of scopes your agent needs:

If a 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 scopes granted to the connection.

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

The client cannot connect

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

Authentication fails

Use OAuth when possible. For API keys, make sure the secret starts with cl_mcp_ and is sent as a bearer token. Do not use an ordinary Cleotic product API key.

The client asks for OAuth app credentials

Some agent clients ask for a client ID, client secret, or token endpoint when they cannot start an interactive OAuth flow. Cleotic MCP does not require you to create a separate OAuth app or share a client secret for normal setup.

If the client supports browser sign-in, start OAuth from the MCP endpoint and authorise Cleotic in the browser. If the client needs manual credentials, create a scoped MCP API key in Settings -> Connected Agents and configure it as:

Authorization: Bearer <cl_mcp_...>

Do not use X-API-Key, an ordinary Cleotic product API key, or a manually supplied client secret for MCP.

Tools are missing

The connection probably lacks the required scope, or the connected user does not have access to the selected organisation or project. Re-authorise with the right scopes or create a more narrowly named MCP key for that client.

A project or segment cannot be found

Use the exact project or segment name, or ask the agent to call list_projects and list_segments first. Unique prefixes are supported, but exact names are safer.

Related

• Profile and organisation
• Team management
• Projects
• Segments
• Responses