MCP server

Radioso’s standalone MCP server lets a client talk to one agent through ask_agent, start any routine the operator has exposed through a typed tool of its own, and read Radioso’s own documentation through radioso_docs and radioso_doc_page. The credential has no workspace role: it is bound to that agent and to the MCP audience.

Two surfaces, two boundaries

• Workspace document work uses the REST API with a personal token or service-account credential.
• Agent chat over MCP binds a client to one agent’s persona, directives, routines, history, and retrieval settings. A signed-in user with permission to manage that agent creates an MCP-audience credential. The server exchanges it for a short-lived converse session.
• Operator MCP connects a user’s preferred engine to Ray’s governed workspace tools through OAuth. The grant follows the user’s live workspace access and is reviewed under Settings → API access. It is a separate resource at /operator/mcp, with its own client identity, grant, and revocation lifecycle.

The dashboard session is the management boundary. It issues, rotates, and revokes agent credentials; agent credentials do not manage credentials or workspace settings.

Deployment enablement

Connect Ray from your favorite engine

Open Settings → API access → Radioso MCP. Choose Codex, Claude Code, ChatGPT, or another MCP client. The chooser shows a versioned setup artifact when that client build has exact-build evidence; otherwise the named client is marked unavailable and the generic route is labeled unverified. Every setup uses the canonical resource URL and starts browser OAuth, so the dashboard selection never counts as a connection by itself.

Operator MCP has five scoped capabilities. operator:read reads bounded workspace and agent state; operator:probe runs bounded diagnostics such as retrieval probes; and operator:propose prepares reviewable routine, retrieval, publication, and document changes — drafting a new knowledge document or changing an existing document’s retrieval eligibility, auto-exclude expiry, and metadata. operator:write applies one exact reviewed change and reads or cancels that bound reviewed operation. Draft, reversible changes use conversational confirmation. Changes that go live, cannot be undone, or use quota require the grant owner to approve the exact digest in the signed-in Radioso review page; approval records consent and execute_reviewed_proposal remains the apply path. A client that declares URL-mode elicitation on protocol 2026-07-28 opens that review page for the person as part of the call, then retries the call once the person responds. Responding means only that they agreed to open the page, not that they approved the change, so that retry waits briefly — up to about 25 seconds — for the approval to land before answering, applying directly if it arrives or answering approval_required again if it does not, in which case the client retries once more. Every other client gets the same review link in the result text to open and approve before asking the agent to retry. These tools reach only an operation a prepare_* tool created; a person approves or dismisses a propose_* proposal in the dashboard. operator:act covers the version-fenced triage-state action.

propose_directive accepts exact name, condition, action, priority, and excludes fields. The supplied text remains verbatim. A new directive needs name, condition, and action when it omits intent; with intent, the coach fills only missing fields. An edit replaces only supplied fields. priority ranges from 0 through 100, and every excludes entry must name a built-in or authored directive on the agent, such as represent-organization.

list_documents lets an operator:read client confirm an import with a cursor-paginated document inventory. It filters by source, status, exact external ids or metadata, case-insensitive title text, and retrieval eligibility; each response has at most 25 rows, and nextCursor continues the inventory. Each row carries identifiers, metadata, content length, and timestamps but never the document body. Enterprise workspaces also expose workspace_usage_limits, which reports the organization plan and each answer, document, and indexing window’s used, limit, remaining, and reset values.

Proposal fences compare only the settings a proposal changes. An unrelated update stays out of its way; a stale result names the changed field, or reports Target deleted when its target disappeared.

Publication stays a separate reviewed operation: prepare an immutable candidate, inspect its changes, then confirm and apply that candidate. Publication goes live, so execution requires the grant’s own user to approve the exact digest on the signed-in Radioso review page; execute_reviewed_proposal applies the candidate only after that approval. The server binds the resulting execution to the grant, client, review digest, target fence, and expiry. A successful consent decision creates a grant tied to one user, workspace, client, and resource; the grant appears in the same API access card and can be revoked there.

The browser consent page lets you choose a workspace and the capabilities the client receives. If a client requests refresh access, approving the connection keeps it connected until that access expires or you revoke the grant.

For a self-hosted deployment, the frontend reads RADIOSO_OPERATOR_MCP_PUBLIC_URL at request time. Point it at the exact public resource, for example https://mcp.example.com/operator/mcp. A deployment must also enable and configure the Operator MCP backend values described in Deployment.

Connect a client

Sign in to the dashboard, open the agent’s Channels → MCP card, and choose Connect a client. Pick the client, name the connection, set an expiry, and Radioso issues a credential bound to that agent and to the MCP audience. The dialog then shows the finished configuration with the secret already in place. Radioso stores only the hash, so copy it before you close the dialog; the Discard exit revokes the credential you just created.

Each client gets its own credential, so rotating or revoking one connection leaves the others working. The examples below use https://mcp.example.com/mcp as the server URL and radioso_mcp_v1_example as the secret.

The card lists the credentials that can reach this agent right now, so revoking one takes its row off the list. To let this agent call tools or other agents, open Skills → Manage MCP connections and add a connection in the side panel.

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit config, merge this block into claude_desktop_config.json, and restart Claude Desktop.

{
  "mcpServers": {
    "radioso": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer radioso_mcp_v1_example"
      }
    }
  }
}

Claude Code

Run this in your terminal:

claude mcp add --transport http radioso https://mcp.example.com/mcp \
  --header "Authorization: Bearer radioso_mcp_v1_example"

Cursor

Open Cursor → Settings → MCP → Add new server, or merge the same mcpServers block into ~/.cursor/mcp.json.

Other MCP clients

Point the client at the server URL and send the secret as a bearer token. Clients that read a configuration file take the standard mcpServers block shown above.

Credential lifecycle

Rotate a connection from its ⋯ menu when a secret leaks or a rotation window comes due: the old secret stops working immediately and the dialog shows the replacement once. Revoke removes access for that client alone.

The dashboard uses the shared agent-credential lifecycle endpoints:

POST /api/v1/agents/{agentId}/channel-credentials
GET  /api/v1/agents/{agentId}/channel-credentials?audience=mcp
POST /api/v1/agents/{agentId}/channel-credentials/{credentialId}/rotate
POST /api/v1/agents/{agentId}/channel-credentials/{credentialId}/revoke

The create request sets audience to mcp and includes label and expiresAt. Lifecycle calls require a signed-in session with agent-manage permission. The operator-minted secret is a static bearer, so Radioso does not require OAuth for this connection.

Radioso documentation tools

A client wired to this server is usually being used to build something against Radioso, so the questions it gets asked are as often “how does this work” as “what does my agent say”. Two tools answer the first kind from Radioso’s own manual:

• radioso_docs lists every documentation page with its slug, one-line summary, and section headings. Start here to find the page that covers a concept.
• radioso_doc_page reads one page by slug — guides/mcp-server, guides/authoring-directives, api/documents-and-search — or one section of it by passing section. A long page comes back as its section outline so you can read the part you need in full, rather than a clipped version of the whole.

The pages ship with the release this server runs, so an answer matches the Radioso the client is connected to. Every page is the same public documentation published at docs.radioso.ai , and each result carries its URL so a client can cite the page it used.

Workspace document tools

Operator MCP’s propose_document and propose_document_retrieval cover two workspace document changes: drafting a new knowledge document, and changing an existing document’s retrieval eligibility, its auto-exclude expiry, and the metadata retrieval filters and boosts on. Both apply through Operator MCP’s reviewed execution, the same as every other proposal tool. The agent-scoped MCP credential this section otherwise describes exposes agent chat only, not document tools.

An existing document’s body, its upload, its reprocessing, and its removal stay on the dashboard and the REST document routes with a personal or service-account credential.

Deployment notes

RADIOSO_MCP_SIGNING_SECRET authenticates the digested source identity that standalone forwards to the backend. When Redis backs the MCP session-token cache, the same domain-separated secret also encrypts that material. It is different from agent credentials, personal tokens, service-account credentials, public-chat launch values, provider keys, and connector secrets.

Authentication boundaries

• MCP accepts an MCP-audience credential or a valid converse session created from one.
• Agent credentials are created, rotated, and revoked through a signed-in session with permission to manage the bound agent.
• A REST-audience credential is rejected by MCP even when it belongs to the same agent.
• Public-chat launch values and website-embed values cannot be reused for MCP converse.
• MCP does not reveal agent, workspace, provider, connector, public-launch, or signing-key secrets.

Common failure modes

• The agent’s MCP card reads “Not enabled on this deployment.” The frontend process has no RADIOSO_MCP_PUBLIC_URL, or its value resolves to the dashboard’s own origin. Set it to the MCP server’s public URL and restart the frontend.
• The MCP endpoint returns 401. Confirm that the bearer is an active, unexpired MCP-audience credential for this agent. A personal token, service-account credential, or REST-audience agent credential is rejected.
• The converse client cannot connect. Confirm the MCP URL is reachable over HTTPS for hosted clients, and check RADIOSO_BASE_URL and the standalone bind settings. When Redis is configured, check RADIOSO_MCP_SIGNING_SECRET too.
• A converse session is rejected. Its credential may be revoked, expired, or issued for a different agent. Create or revoke credentials from the agent’s MCP card with a current dashboard session.
• A routine call returns 404 routine_tool_unknown. The routine is not exposed, is switched off, or is only in the agent’s draft. Switch exposure on in the routine editor and publish the agent; the tool appears in the next session’s catalog.
• An exposed routine is missing from tools/list. The session opened before the routine was exposed and published. The standalone server pins the catalog at session exchange, so let the session expire or exchange the credential again and the tool is listed.

Read next

• Connect a calling agent — ask_agent, the reply envelope, and calling an exposed routine as a typed tool.
• Publish and open an agent — the agent’s public id, its discovery documents, and credential-free access.
• Authentication — sessions, personal tokens, service credentials, and public launch flows.
• Personal tokens and service accounts — issue REST credentials and store their one-time secrets.
• Agents and skills — configure the agent and its external MCP skills.
• Documents and search — use the REST document routes for workspace document work.