MCP Server

Ragtime runs a Model Context Protocol server, so AI tools such as Claude Code, Cursor, VS Code and Claude Desktop can use your assistant and knowledge base directly: ask the assistant, search and read your sources, add documents, check credits and question your conversation insights.

The server lives in your Ragtime instance. There is nothing to install or host.

The dashboard has the same steps under Integrations → MCP, with your server URL and the snippets ready to copy.

Endpoint and authentication

URL	https://your-ragtime-instance.com/api/mcp
Transport	Streamable HTTP
Authentication	An API key (Authorization: Bearer rt_live_…), or sign-in for apps that support it

Tools configured by hand use an ordinary project API key. Apps that support sign-in, such as Claude.ai and ChatGPT, sign in instead and get the same kind of access. Either way, the credential decides everything the AI tool can do:

• Which tools it gets. A tool only appears when the key has the scope it needs, so the AI never sees a tool that would be refused.
• Which content it sees. Retrieval follows the key’s retrieval audiences, exactly as the REST API does.
• Which credits it spends. A key billed to a channel draws on that channel’s package, and a monthly credit cap limits how much the AI tool can spend.

Create a key for the MCP server

Give it only the scopes for the tools you want (see Tools). A key for answering questions needs assistant:ask, kb:read and usage:read. Add kb:content:read to let it read whole documents, and ingest to let it add them.

Set up your AI tool

Claude Code

claude mcp add --transport http ragtime https://your-ragtime-instance.com/api/mcp \
  --header "Authorization: Bearer rt_live_YOUR_KEY_HERE"

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "ragtime": {
      "url": "https://your-ragtime-instance.com/api/mcp",
      "headers": { "Authorization": "Bearer rt_live_YOUR_KEY_HERE" }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "ragtime": {
      "type": "http",
      "url": "https://your-ragtime-instance.com/api/mcp",
      "headers": { "Authorization": "Bearer rt_live_YOUR_KEY_HERE" }
    }
  }
}

Claude Desktop

Claude Desktop connects to a remote server with a header through the mcp-remote bridge. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ragtime": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-ragtime-instance.com/api/mcp",
        "--header",
        "Authorization:${RAGTIME_AUTH}"
      ],
      "env": { "RAGTIME_AUTH": "Bearer rt_live_YOUR_KEY_HERE" }
    }
  }
}

Claude.ai, ChatGPT and other apps that sign in

Apps that support custom MCP connectors with sign-in need only the URL. Add a custom connector in the app with:

https://your-ragtime-instance.com/api/mcp

The app opens a Ragtime page where you sign in and choose:

• Project: which project the app may use. You see projects where you are an organization admin or the project owner.
• What it may do: the scopes, the same ones an API key has. The ones the app asked for are preselected.
• Channel (optional): bill the app’s AI usage to a channel, as with an API key.

After you allow it, the app connects with a token that lasts an hour and renews itself. You never copy a key.

What it sees	The same content an API key without audiences sees: libraries without audience restrictions.
How long it lasts	Until you disconnect it, or you leave the organization.
Disconnecting	Dashboard → Integrations → Connected apps → Disconnect ends its access at once.

For developers of MCP clients

The server follows the MCP authorization spec: OAuth 2.1 with dynamic client registration (RFC 7591), PKCE with S256, protected-resource metadata at /.well-known/oauth-protected-resource (RFC 9728), and authorization-server metadata at /.well-known/oauth-authorization-server (RFC 8414). Clients are public: no client secret. Refresh tokens are single use and rotate on every refresh.

What the AI sees first

When a session starts, the server tells the AI which project it is connected to, which tool fits which job, which tools spend credits, and whether any credits are left. This saves the AI from probing tools to find out, and from spending credits on calls that would be refused.

Tools

Tool	What it does	Scope	Credits
ask_assistant	Asks the published assistant and returns its answer with the sources it used. Pass back conversation_id to continue a conversation, and end_conversation on the last question. With assistant:draft, it can also ask the draft.	assistant:ask	Every call
search_knowledge	Returns matching passages, each with the name and id of its document, to reason over.	kb:read	Only with query
list_sources	Lists documents with their id, library, topics and how often they answered visitors.	kb:read	Free
read_source	Reads a whole document, in pages.	kb:content:read	Free
add_source	Adds a document from a URL or text and waits for it to be searchable.	ingest	Embedding, while processing
get_usage	Shows credits left, the pool they come from, and rate limits.	usage:read	Free
query_insights	Answers questions about conversations: what people asked and how it went.	insights:read	Yes, with a computed fallback
find_knowledge_gaps	Lists what the assistant could not answer, grouped by meaning, most asked first. Pairs with add_source to fill the gaps.	insights:read	Free
list_findings	Lists the findings of the daily check, most impact first, with the questions behind each and what to do about it.	insights:read	Free
run_workflow	Runs a published workflow and reports its result.	workflows:execute	Depends on the workflow
get_assistant	Reads the instructions and conversation stages.	assistant:read	Free
configure_assistant	Changes the instructions and conversation stages on the draft. Stages are reviewed on save.	assistant:write	The stage review
list_actions, get_action	List the actions, and read one ready to change.	actions:read	Free
save_action, delete_action	Create, change or delete an action on the draft.	actions:write	Free
get_page_events, save_page_events	Read and change the page events on the draft.	assistant:read, assistant:write	Free
list_workflows, get_workflow	List workflows and what they may refer to, and read a draft.	workflows:read	Free
save_workflow, delete_workflow	Create or change a workflow draft, or remove a workflow.	workflows:write	Free

Every other API operation

Everything else the API can do is a tool too, one per operation, named after it: listLibraries becomes list_libraries, runSavedInsightQuery becomes run_saved_insight_query. That covers libraries and audience labels, saved insight queries, findings, insight settings and test data, lenses and distillation, campaigns and recipients, and analytics.

• Built from the API reference. Each tool’s description, inputs and credit cost come from the operation’s entry in the OpenAPI document, so they always match the API. The project is filled in for you; a request body goes in body.
• Same scopes. A tool appears only when the key or app has the operation’s scope.
• The tools above come first. Where a tool in the table fits, the AI should use it: it does more per call, such as waiting for a document to be processed. The session instructions say so.
• Not offered: operations that return or upload a file, which a model cannot handle as a tool result: exportInsights, and the two calls of a recipient material upload.

A key with every scope gets about 60 tools. Some AI clients choose less well among that many, so give a key only the scopes the AI needs.

Building the assistant with an AI tool

With the write scopes, an AI tool can set up the assistant: its instructions, conversation stages, actions, page events and workflows. Everything it writes goes to the draft:

• Testing. Test with ask_assistant and draft: true (needs assistant:draft).
• Going live. Visitors get the changes only when someone publishes in the dashboard, and workflows run only once published and enabled there.

Give these scopes only to keys and apps you use for building, not to production integrations.

Each tool tells the AI client whether it changes anything. Clients use this to decide what to run without asking you:

• search_knowledge, list_sources, read_source, find_knowledge_gaps, list_findings and get_usage only read.
• ask_assistant, query_insights and add_source spend credits or add content.
• run_workflow is marked as able to change other systems, so clients ask before running it.
• The other tools follow their operation: reads only read, while updates, replacements and deletes are marked as changing data.

Resources

The server also offers read-only context the AI can load without a tool call:

Resource	Contents	Scope
ragtime://context	The key, the project, every operation the key may call and what it spends, rate limits and credit availability. Same as GET /api/v1/context.	Any key
ragtime://assistant	The assistant’s instructions and conversation stages.	assistant:read
ragtime://topics	The topics the knowledge base covers.	kb:read

Limits, credits and errors

Every tool call is a call to the REST API, made with your key. It follows the same scopes, rate limits and credits, and shows up in usage and analytics like any other call.

• Rate limits. Tool calls count against the key’s API rate limit. The protocol’s own traffic, such as starting a session and listing tools, has a separate allowance, so it never uses up the key’s API quota.
• Errors. A failed tool call returns the API’s error code, message and hint, for example credits_exhausted: … Credits reset at the start of the next billing period., so the AI can act on it or tell you.
• Sessions. The server is stateless. Each request carries the key; conversations continue through conversation_id.