MCP server

Point an MCP client at a Radioso workspace and it can list and search documents, pull a grounded answer with citations, and create or update content — the same operations the dashboard and REST API expose, reached as MCP tools instead of HTTP calls. Point a converse-capable client at one agent instead, and it holds an actual conversation with that agent’s persona, directives, and routines, the way a user would.

This page is about Radioso running an MCP server that a client connects into. If you’re looking for the other direction — an agent skill that calls out to someone else’s MCP server as a tool — see Agents and skills. The two are unrelated: this page’s server accepts MCP calls, that skill kind makes them.

Two surfaces, two credentials

Radioso’s MCP server exposes two surfaces, and they don’t share credentials — a workspace API token is rejected by the converse endpoints, and a converse grant or converse session token is rejected by the workspace tools.

• Workspace document tools are retrieval-first and scoped to a whole workspace. They authenticate with a workspace API token and don’t carry any agent’s persona or configuration. Use this surface when a client should search, read, or manage the workspace’s documents.
• Agent converse surface binds a client to one agent’s turn loop. It authenticates with a per-agent converse grant, exchanged for a short-lived session token. Use this surface when the client should hold a conversation and behave like that agent.

Both surfaces call the same underlying Radioso backend, but the workspace tools never apply an agent’s persona, directives, or routines — they answer from retrieval alone.

Enable it

Workspace document tools

Client config: Cursor

Same-host merged mode, using the workspace API token directly:

{
  "mcpServers": {
    "radioso": {
      "url": "https://api.radioso.ai/mcp",
      "headers": {
        "Authorization": "Bearer radioso_your_workspace_token"
      }
    }
  }
}

Local development against a backend you’re running yourself:

{
  "mcpServers": {
    "radioso-local": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer radioso_your_workspace_token"
      }
    }
  }
}

Standalone mode needs a short-lived access token instead of the workspace token. Exchange one from the standalone server’s origin:

source <(
  RADIOSO_WORKSPACE_TOKEN=radioso_your_workspace_token \
  pnpm --dir packages/radioso-mcp-server run -s token:exchange
)

That sets RADIOSO_MCP_ACCESS_TOKEN in your shell. Point Cursor’s config at the standalone server with that token:

{
  "mcpServers": {
    "radioso": {
      "url": "http://127.0.0.1:8787/mcp",
      "headers": {
        "Authorization": "Bearer ${env:RADIOSO_MCP_ACCESS_TOKEN}"
      }
    }
  }
}

Rerun the exchange when the token expires (RADIOSO_MCP_ACCESS_TOKEN_TTL_SECONDS, default 900 seconds).

If you open Cursor from the Dock, Spotlight, or a launcher instead of a terminal, install the token into the GUI app’s environment first, since a GUI-launched app doesn’t inherit your shell’s exported variables:

RADIOSO_WORKSPACE_TOKEN=radioso_your_workspace_token \
pnpm --dir packages/radioso-mcp-server run -s cursor:prepare -- --open

Cursor can also spawn the MCP server itself over stdio instead of connecting to a running HTTP process — set RADIOSO_BASE_URL and RADIOSO_API_TOKEN and point Cursor’s config at dist/src/cli/stdio.js.

Client config: Claude Desktop

Claude Desktop’s remote connector runs from Anthropic’s infrastructure, not your laptop, so http://127.0.0.1:8787/mcp and http://localhost:8080/mcp are both unreachable from it. It needs a public HTTPS deployment:

1. Deploy the MCP server (merged or standalone) behind a public HTTPS URL, for example https://mcp.example.com/mcp.
2. In Claude, open Customize → Connectors and add a custom connector pointed at that URL.
3. Authenticate the connector with a token minted through the exchange flow above; the package doesn’t implement a native OAuth connector flow, so if your deployment fronts the exchange endpoint with its own OAuth layer, supply that client ID and secret in Claude’s advanced settings instead.
4. Enable the connector in a conversation.

For localhost-only Claude Desktop access, use the stdio compatibility entrypoint described above rather than the remote connector flow.

The tools

• describe_capabilities — no arguments. Returns the read and write tools this session was granted, any tools that require host-side approval, and basic workspace and upstream API metadata.
• list_documents — optional cursor (string), limit (1–100), offset (integer ≥ 0). Lists workspace documents.
• get_document — documentId (string, required). Fetches one document.
• search_documents — query (string, required, up to 4000 characters), optional metadataFilter. Searches workspace documents.
• answer_grounded — query (string, required), optional metadataFilter, optional conversationContext (previousUserMessages, previousAssistantMessages, followUpToMessageId) for rewrite continuity across a caller-managed thread. Returns a grounded answer with citations from workspace retrieval. It does not create an assistant conversation and does not carry any agent’s persona.
• create_document (requires approval by default) — title and content (strings, required), optional metadata, optional externalDocumentId.
• update_document (requires approval by default) — same fields as create_document plus documentId (required).
• delete_document (requires approval by default) — documentId (string, required).
• reprocess_document (requires approval by default) — documentId (string, required), optional documentEnrichmentOverride ("on" or "off"). Requeues the document through the backend’s document processing path; the override applies only to the job this call creates, not to workspace or source-level ingestion settings.

describe_capabilities, list_documents, get_document, search_documents, and answer_grounded are read tools. The other four are write tools, and every write tool advertises requiresApproval: true in its MCP tool definition by default, so hosts that read that field — Cursor, Claude Desktop, the ChatGPT app — show their own confirmation prompt before calling it. The Radioso MCP server itself has no separate server-side approval gate beyond the workspace API token’s own permissions; a headless client that ignores requiresApproval can still call a write tool if the token allows it.

An operator can narrow which tools are granted per workspace with RADIOSO_MCP_ALLOWED_READ_TOOLS, RADIOSO_MCP_ALLOWED_WRITE_TOOLS, RADIOSO_MCP_APPROVAL_REQUIRED_WRITE_TOOLS, or a RADIOSO_MCP_WORKSPACE_POLICIES_PATH policy file keyed by workspace ID. Left unset, all nine tools above are granted and all four write tools require approval.

Agent converse surface

The converse surface authorizes exactly one agent — the client never sees other agents, workspace settings, or document management outside that agent’s own documents.

Mint a converse grant

A workspace admin creates a grant with the workspace API token. The plaintext token is returned once, on creation:

POST /api/v1/agents/{agentId}/mcp-converse-grants
Authorization: Bearer <workspace API token>
Content-Type: application/json
 
{ "label": "Cursor on my laptop" }

{
  "grant": { "id": "...", "label": "Cursor on my laptop", "tokenPrefix": "radioso_", "createdAt": "..." },
  "token": "radioso_..."
}

GET, rotate (POST .../rotate), and DELETE on the same path list, rotate, and revoke a grant. Revoking, disabling, or rotating a grant stops its existing sessions immediately, because every converse request re-checks the grant.

Exchange the grant for a session

POST /api/v1/mcp/converse/session
Content-Type: application/json
 
{ "launchToken": "radioso_...", "client": { "name": "cursor" } }

{
  "sessionToken": "<session token>",
  "expiresAt": "...",
  "agent": { "id": "...", "name": "Support" },
  "conversationId": "..."
}

Use the returned sessionToken as the bearer token for the tools below. There’s no agent ID in those requests — the agent is fixed by the grant. Re-exchange the grant when the session expires.

The tools and resources

• ask_agent — message (string, required). Runs the agent’s full turn loop — persona, directives, routines, history — and continues the same conversation across calls. This is the stateful, interactive tool.
• answer_grounded — query (string, required), optional maxResults (1–20). Returns one grounded answer with citations from the bound agent’s own retrieval configuration: its query rewrite, rerank, source scope, and citation policy. Stateless and read-only, with no conversation, persona, or routines. This is a different tool from the workspace-scoped answer_grounded above — same name, agent-bound instead of workspace-bound, and a smaller argument set.
• Agent documents as MCP resources — GET /api/v1/mcp/converse/resources lists resources scoped to what the agent can see; GET /api/v1/mcp/converse/resources/{resourceId} reads one. Content is sanitized for a public surface — no internal document or chunk IDs.

Authentication boundaries

• The converse surface accepts only converse session tokens minted through the exchange above. A workspace API token is rejected.
• A converse grant is bound to the mcp-converse channel; embed and public-chat launch tokens are rejected, so a public website token can’t be reused to converse over MCP.
• A converse grant is a secret credential — unlike an embed token, it’s never exposed in client-side surfaces. Store it the way you’d store any workspace secret.
• There’s no standard MCP OAuth 2.1 front door for the converse surface. Public connectors such as Claude or ChatGPT authenticate with a session token minted through the grant exchange, held server-side by whatever fronts the connector.

Auth and token model, end to end

Every path above still starts from a workspace API token — the standalone exchange and the converse grant both need one to mint their own shorter-lived credential. See Authentication for how to get one.

Common failure modes

• 401 from the MCP endpoint in merged mode — usually a workspace API token that’s missing, revoked, or issued by a different Radioso instance than the one you’re calling.
• A tool call succeeds against the workspace tools but the converse tools reject the same token, or vice versa — expected. The two surfaces don’t share credentials by design; use a workspace API token for /mcp document tools and a converse session token for /api/v1/mcp/converse/*.
• Claude Desktop or a ChatGPT app can’t reach a locally running MCP server — these are hosted remote connectors that call from provider infrastructure, not from your machine. Deploy the server behind a public HTTPS URL, or use the stdio entrypoint for local-only access instead.
• A write tool call is silently skipped in a host UI — the host is honoring requiresApproval: true and waiting for you to confirm. Check the host’s own approval prompt rather than the Radioso server logs.
• Standalone mode refuses to start — RADIOSO_MCP_SIGNING_SECRET must be an explicit, non-default value in remote HTTP mode; the built-in stdio compatibility secret is rejected outside stdio.
• reprocess_document didn’t change how future uploads are enriched — documentEnrichmentOverride only applies to the single reprocessing job that call created, not to the workspace ingestion setting or the source-level override.

Read next

• Authentication — how workspace API tokens and sessions work across all of Radioso’s surfaces.
• Agents and skills — the reverse direction: binding an agent skill to an external MCP server.
• Documents and search — the REST endpoints the workspace document tools call.
• Chat and history — the assistant chat API the converse surface’s ask_agent runs underneath.