MCP server

Expose your Asks agent as a remote MCP server so Claude Code, Cursor, and other AI clients can talk to it.

The MCP server Premium exposes your workspace's AI agent as a remote MCP server. Any MCP-capable client — Claude Code, Cursor, Codex, Claude Desktop — gets a tool that asks your agent questions and receives answers grounded in your knowledge base.

This is the opposite direction of MCP servers for your agent, where your Asks agent consumes external MCP servers as tools. This page is about other AI clients consuming your agent.

Code

POST https://api.asks.app/v1/mcp

The endpoint speaks JSON-RPC 2.0 over plain JSON POST (no SSE stream or session to manage). Authentication is a Bearer API key; calling tools requires the agent:chat scope.

Enable it

Turn on the MCP server

Go to app.asks.app/integrations/mcp and turn on the MCP server. You can rename the tool (snake_case, e.g. ask_acme), edit its description — that's what tells client LLMs when to call it — and optionally expose a read-only search_knowledge tool.

Configure and connect dialog on the Agent API page with the command tool name and description fields and the expose knowledge-base search toggle — Name the tool, write its description, and copy a connect snippet.

Mint a key and connect a client

The MCP server page generates an API key with the agent:chat and agent:read scopes and fills it into ready-to-copy snippets. For Claude Code:

Terminal

claude mcp add --transport http asks https://api.asks.app/v1/mcp \
  --header "Authorization: Bearer ask_live_YOUR_KEY"

For Cursor, add to .cursor/mcp.json:

JSON

{
  "mcpServers": {
    "asks": {
      "url": "https://api.asks.app/v1/mcp",
      "headers": { "Authorization": "Bearer ask_live_YOUR_KEY" }
    }
  }
}

Any generic MCP client works the same way: HTTP transport, URL https://api.asks.app/v1/mcp, and an Authorization: Bearer … header.

Enabling the MCP server also deploys the agent on the API channel, so MCP conversations appear in your inbox like any other channel. Disabling it turns the channel back off.

The tools

send_messagetool

Asks your agent a question and returns the reply. The tool name and description are configurable on the MCP server page. Arguments: message (required), conversation_id (continue a previous exchange), and response_format (concise or detailed).

search_knowledgetool

Optional and off by default. Read-only semantic search over your published, AI-enabled knowledge base. Arguments: query (required) and top_k (1–20, default 8).

Each send_message result includes a conversation_id; clients pass it back to keep multi-turn context, exactly like the agent chat API.

Billing and limits

Every send_message call is a normal agent turn: it consumes AI credits by the agent's model tier (Essential 1, Pro 4, Ultra 8 per reply) and creates a real conversation. The endpoint uses the chat rate tier — 20 requests per minute per key, 60 per workspace.

Troubleshooting

Tool calls "succeed" but contain an error message

Failures inside a tool call follow MCP semantics: the JSON-RPC response succeeds, and the tool result carries isError: true with a plain-text explanation — for example "This assistant has reached its usage limit. Please try again later." when the workspace is out of AI credits, or "This assistant is currently unavailable." when the agent is disabled. Client LLMs read these as failed tool calls; your own integration should check isError, not just the HTTP status.

The client connects but tool calls fail

Tool calls need the agent:chat scope — a key without it gets JSON-RPC error -32001 on tools/call. The handshake (initialize, tools/list) deliberately works with any valid key, so a connection test can pass while calls fail — use the key minted on the MCP server page.

"MCP is not enabled for this workspace"

The toggle at app.asks.app/integrations/mcp is off, or the workspace no longer has a Premium plan (a downgrade turns the MCP server off automatically).

GET requests return 405

Expected. The server is stateless JSON-RPC over POST only — there is no SSE stream. Point clients at the HTTP (not SSE) transport.

← Previous

Webhooks

Widget developer guide