Knolo Connector (MCP): connect Cursor, Claude, and ChatGPT to your Space

A Knolo Connector is a per-Space remote Model Context Protocol (MCP) server. It lets external AI clients — Cursor, Claude, ChatGPT, and any MCP-capable agent — search your Space's knowledge, read its Minds, ask its Assistants, and run its Agents through one authenticated endpoint. A Connector has full read access to the whole Space; a single Allow writes switch decides whether it can also make changes.

If you just want to read and write your knowledge base over plain HTTP instead, use the Knolo CMS API.

What is a Knolo Connector?

A Connector turns a Knolo Space into a backend for someone else's agent. Where the CMS API is a REST surface for data, a Connector speaks MCP — the open protocol that AI clients use to discover and call tools, read resources, and load prompts. One Connector always belongs to exactly one Space.

• Tools let a client take actions: search knowledge, ask an Assistant, run an Agent.
• Resources expose your Minds and files as read-only context the client can pull in.
• Prompts expose your Knolo Skills as reusable starting instructions.

How it works

1. A Space owner or editor creates a Connector in Space Settings → Connectors. Knolo shows a secret key (prefix knc_) exactly once.
2. You add the Connector's endpoint URL and key to your MCP client.
3. The client connects over MCP Streamable HTTP and discovers the tools, resources, and prompts the Connector Policy allows.
4. Every paid action (asking an Assistant, running an Agent) is billed to the Space's wallet and attributed to the Connector.

The endpoint is stateless: conversation memory for ask_assistant is anchored to a stable thread per Connector (optionally per conversationId), so follow-up questions keep context.

Before you start

• You need a Knolo Space and the owner or editor role.
• Decide whether the Connector may make changes. Read access covers the whole Space; writes and Agent runs are off until you turn on Allow writes.
• Have your MCP client ready (Cursor, Claude Desktop, ChatGPT, or your own agent).

Create a connector

1. Open Space Settings → Connectors.
2. Copy the MCP endpoint URL shown at the top of the section. It looks like:

https://europe-west3-knowledgio-v3.cloudfunctions.net/mcp

3. Click Create connector, give it a label (e.g. "Cursor"), and set its policy:

   • Allow writes — off by default. When off, the Connector has full read access to the whole Space (all Minds, all Assistants) but cannot change anything. When on, it can also write_file, upload_file, use the Assistant's write/integration tools, and run any Agent (run_agent).
   • Credit ceiling — an optional spend cap for this Connector.

4. Copy the generated key (prefix knc_) immediately. You will not be able to see it again.

   Read access is always Space-wide: every Mind is searchable and any Assistant can be asked. There are no per-Mind, per-Assistant, or per-Agent allowlists.

Connect your client

Authenticate with the key as a Bearer token: Authorization: Bearer knc_your_key.

Cursor

Add the server to your mcp.json (Cursor Settings → MCP → Add new server):

{
  "mcpServers": {
    "knolo": {
      "url": "https://europe-west3-knowledgio-v3.cloudfunctions.net/mcp",
      "headers": {
        "Authorization": "Bearer knc_your_key"
      }
    }
  }
}

Claude Desktop

Add a remote MCP server in Settings → Connectors (or your claude_desktop_config.json) pointing at the same URL with the same Authorization header. For clients that only support local (stdio) servers, bridge to the remote endpoint with a tool such as mcp-remote.

ChatGPT and other agents

Any MCP-capable client works: provide the endpoint URL and the Authorization: Bearer knc_your_key header. The client will list the tools and resources your policy permits.

Verify the connection

After connecting, your client lists the tools your policy permits, led by ask_assistant. The simplest test is to just talk to the Assistant: "Ask my Knolo assistant to summarize our refund policy." (Direct helpers like search_knowledge exist too, but ask_assistant is the main way in.)

Tools

ask_assistant is the primary interface. For almost everything — answering questions, finding or summarizing knowledge, and (when writes are on) creating or editing files and getting work done — call ask_assistant. The Assistant has the Space's full knowledge and tools: it does the task and replies, and you can then read any file it created. The other tools are narrow helpers, not the default path. If a client ever reports it "has no tool" for a request, the answer is almost always to route that request through ask_assistant.

Read tools are always available; write/agent tools appear only when Allow writes is on.

When writes are disabled (the default), only a safe read-only subset of the Assistant's own tools is available inside ask_assistant — no file writes, agent calls, or integration actions. Agents are gated by the same switch because they can write and call integrations.

Creating files: prefer the Assistant

To put content into a Mind, the default is to ask the Assistant to create it. The Assistant has the Space's knowledge and data, writes the file, and replies; the client then just reads the finished file (via search_knowledge or the knolo://minds/... resources). Reserve the direct file tools for these specific cases:

• write_file — the client already holds the exact verbatim text and explicitly wants it stored as-is.
• upload_file — the client is holding local file bytes (a PDF, image, spreadsheet, large document) that must be uploaded. This is the one thing the Assistant cannot do for you. Steps:
  1. Call upload_file with the mindId, filename (with extension), and optional contentType. It returns a short-lived upload.url.
  2. PUT the raw file bytes to that URL, sending the exact Content-Type header it returns.
  3. The file is parsed and indexed automatically once the upload finishes — there is no follow-up call.

Resources

Connectors expose read-only MCP resources for the whole Space:

• knolo://minds — a JSON index of the Space's Minds.
• knolo://minds/{mindId}/{fileId} — the contents of a file inside a Mind. Binary files return a download pointer instead of bytes.

Prompts (Knolo Skills)

Your Space's available Knolo Skills are exposed as MCP prompts. Selecting one returns the Skill's blueprint as a starting instruction your client can adopt. Skills are read-only context here; they do not unlock extra tools on the Connector.

The Connector Policy

The Connector Policy is the set of governance rules attached to a Connector: whether writes are allowed and an optional credit ceiling. Read access always spans the whole Space.

• Read-only by default. A new Connector can search all Minds and ask any Assistant, but cannot change anything until Allow writes is on.
• Writes are all-or-nothing. Turning on Allow writes unlocks file writes/uploads, the Assistant's write and integration tools, and Agent runs together.
• Edit anytime. Toggle a Connector's writes, disable it, or revoke it from Space Settings → Connectors. Revoking invalidates the key immediately.

Billing and limits

• Connector work is billed to the Space's Billing Account, attributed to the Connector.
• A pre-flight balance check blocks new paid turns when the wallet is empty.
• An optional per-Connector credit ceiling caps how much a single Connector can spend.
• search_knowledge, list_minds, and resource reads are lightweight; ask_assistant and run_agent consume credits like normal Assistant and Agent runs.

Security

• Keys are shown once and stored only as a SHA-256 hash — Knolo cannot recover a lost key. Create a new one if you lose it.
• Each Connector is bound to the member who created it. If that member leaves the Space (loses participation), the Connector key stops working automatically — a credential never outlives its owner's access.
• Use a separate Connector per client so you can revoke one without affecting others.
• Keep Allow writes off unless a client genuinely needs to write back.
• Disable or revoke a Connector the moment a client no longer needs access.

Troubleshooting

• 401 Unauthorized — the key is missing, malformed, disabled, or revoked. Confirm the Authorization: Bearer knc_... header and that the Connector is enabled.
• ask_assistant says there are no assistants — the Space itself has no assistants yet. Create one in the Space first.
• "Out of credits" — top up the Space's Billing Account, or raise the Connector's credit ceiling.
• run_agent / write tools not visible — they only appear when Allow writes is on.

FAQ

What is the difference between a Connector and the CMS API?

The CMS API is a REST interface for reading and writing Minds and entries over HTTP. A Connector is an MCP server that lets AI clients call tools, read resources, and load prompts — including delegating to your Assistants and Agents.

Which clients can connect?

Any MCP-capable client, including Cursor, Claude Desktop, ChatGPT, and custom agents built on the MCP SDK.

Is a Connector read-only?

Yes by default — it can read the whole Space but not change anything. Writes, Agent execution, and integration actions turn on together via the per-Connector Allow writes switch.

How do I revoke access?

Open Space Settings → Connectors and revoke the Connector. Its key stops working immediately. A Connector also stops working automatically if the member who created it leaves the Space.

What happens to a Connector when its creator leaves the space?

It is disabled automatically. Each Connector is bound to its creator, and its key is rejected once that member is no longer a participant of the Space. If they rejoin, the key works again; to keep access permanently, have a current member recreate the Connector.

Related

• Knolo CMS API — REST access to Minds and entries.
• Documentation overview — Spaces, Minds, Assistants, Agents, Triggers.
• Model Context Protocol — the open standard Connectors implement.