Connect an AI agent (MCP)
Connect an AI agent to AskRAI's hosted MCP server with a credential of Channel MCP, so it can ask governed questions of your knowledge base
AskRAI hosts an MCP server that lets an AI agent, such as Claude, Copilot, Cursor or one you built, ask governed questions of your knowledge base. Every question an agent asks is answered from the knowledge packs and guardrails of the credential it connects with, counted against your rate limits, and recorded in your conversation logs like any other.
What you need
| Setting | Value |
|---|---|
| Server URL | https://mcp.askrai.ai/mcp, over the Streamable HTTP transport |
| Authentication | An API key created with Channel MCP, sent in every request as Authorization: Bearer <key> |
| Interface | MCP turned on in the Interfaces panel of Programmable Access |
The server signs an agent in with its API key alone and offers no OAuth sign-in, so the agent's client must let you set a request header for a remote MCP server.
Connecting an agent
Turn on the MCP interface
Open Admin → Programmable Access and turn on MCP in the Interfaces panel. While it is off, every credential with Channel MCP is refused, however it is configured, so turning it off is also how you disconnect every agent at once.
Create a credential with Channel MCP
Click Create Credential and fill in the form as Creating a credential describes, with these choices:
- Channel:
MCP. The MCP server admits no other Channel: a key created with ChannelAPIis refused withThis key is for the API channel; create a key with Channel MCP., aCLIone is told the same, naming CLI, and anA2Aone is refused withAn A2A key calls only the A2A endpoint of an agent that lists it. - Group: the group whose knowledge packs and guardrails the agent should answer from. With None, no group's knowledge packs or guardrails apply to the agent's questions.
- Credential Type
Agent Credentialand Caller TypeAgent, so the agent's questions are labelled as an agent's in the conversation logs and on the dashboard. - IP Allowlist: leave it empty. The address it is checked against is the one the MCP server reaches AskRAI from, not the agent's, so an allowlist of the agent's addresses refuses every request.
Click Create and copy the key: it is shown only once.
Add the server to the agent's client
Give the client the server URL and the key as a Bearer token, as the examples below show.
Check the connection
Ask the agent to list its AskRAI tools, then to use askrai_query on a question your knowledge base answers. The question appears in Conversation Logs with Channel MCP.
Example client configuration
Claude Code
claude mcp add --transport http askrai https://mcp.askrai.ai/mcp \
--header "Authorization: Bearer $ASKRAI_API_KEY"Cursor
In mcp.json, with the key read from the ASKRAI_API_KEY environment variable:
{
"mcpServers": {
"askrai": {
"url": "https://mcp.askrai.ai/mcp",
"headers": {
"Authorization": "Bearer ${env:ASKRAI_API_KEY}"
}
}
}
}Other clients name these settings differently: give yours the server URL and an Authorization header holding Bearer and the key.
Anyone holding the key can ask questions as its credential until you revoke it. Keep it in a secret store or an environment variable, and never in a configuration file that is checked into version control.
Request bodies
The MCP server takes each message the agent's client sends to https://mcp.askrai.ai/mcp with a Content-Length header or chunked, as the official C# MCP SDK sends them on .NET 8 and later, up to 121,024 bytes. A longer message fails its tool call: a chunked one is answered 413 as soon as that much of it has arrived, and one whose Content-Length declares more is refused before it reaches the MCP server, with 403 and an HTML page. The public API's query endpoints take bodies the same way: see Request bodies.
Tools
| Tool | What it does | Arguments |
|---|---|---|
askrai_query | Asks a governed question of your knowledge base. Returns the answer with its status, confidence, guardrail results and citations, a thread_id and an audit_ref | prompt (required), thread_id, execution_mode |
askrai_chat | Asks a further question in an existing conversation, the one the thread_id of an earlier answer names | prompt and thread_id (both required), execution_mode |
askrai_get_audit | Retrieves the audit record of an earlier question asked with the same credential: what was asked and answered, its confidence, and whether a guardrail fired. For up to two minutes after the answer, the record may not be there yet | audit_ref (required) |
An answer's status is delivered, blocked or low_confidence. execution_mode is interactive_user or agent_augmentation. Left out, the least-augmenting mode the credential allows applies, and a mode the credential does not allow is refused. agent_augmentation adds an agent_context block beside the answer, with a suggested next action, the reason an answer was blocked, whether it was grounded in your knowledge, and its source type: see Execution Modes.
Limits and refusals
Each askrai_query and askrai_chat call is one query, held to the credential's and the tenant's rate limits. askrai_get_audit is not counted. A tool call that is refused fails with the reason AskRAI gave, for example API error (429): This credential's budget of 60 requests per minute is spent. It renews in 23 seconds.
A key the server does not admit is refused when the agent connects, with a reason the client may show:
| Reason | What to do |
|---|---|
AskRAI did not recognise this API key. Check that it was copied whole and has not been revoked or deleted. | Copy the key again, or rotate the credential to issue a new one |
This key is for the API channel; create a key with Channel MCP. | Create a credential with Channel MCP |
An A2A key calls only the A2A endpoint of an agent that lists it | Create a credential with Channel MCP: a key made for an agent's External access calls nothing else |
The MCP interface is turned off for this organization | Turn on MCP in the Interfaces panel. A key of another Channel whose interface is off names that interface instead: create a credential with Channel MCP |
This key's group no longer exists, is inactive, or does not list the key, so the key is refused until an administrator restores it. | Reactivate the credential's group or restore the credential to it. Rotating the key puts it back in its group if the group still exists |
This key's IP allowlist does not include the address the MCP server reaches AskRAI from. | Create a credential with no IP allowlist |
Credential has expired | Create a new credential |
Too many API keys from this address were refused. Try again after the time Retry-After gives. | Fix the key the agent sends, then try again after a minute |
AskRAI could not check this API key just now. Try again in a minute. | Try again in a minute |
Turning MCP off reaches an agent that is already connected: its next tool call is refused, and connecting or listing tools within a minute. A revoked, rotated or deleted key stops working as Viewing credential details describes.
Related pages
- Programmable Access — interfaces, rate limits, and every credential field
- Conversation Logs — filter by the MCP channel and the Agent caller type to see what agents asked
- API Reference — the public API that the MCP tools call