Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

Use MCP tools when you want the MKA1 API to call tools from an external MCP server during a response. Define the MCP server in tools. Limit which tools the model can call with allowed_tools. Use require_approval when you want your app to pause and ask the end user before the tool runs. Use X-On-Behalf-Of for the MKA1 API end user. Pass upstream MCP server credentials in the MCP tool definition.

​
Call an MCP tool directly

Set require_approval to 'never' when the tool can run immediately. 
mka1 llm responses create --body '{
  "model": "auto",
  "instructions": "You are a project management assistant with access to Linear via MCP. Use Linear tools when the user asks about tasks, bugs, or projects. Keep the final answer terse.",
  "input": "List my most recent Linear issue assigned to me.",
  "store": true,
  "stream": false,
  "tools": [
    {
      "type": "mcp",
      "server_label": "Linear MCP",
      "server_description": "Access Linear issues through MCP.",
      "server_url": "https://mcp.linear.app/mcp",
      "allowed_tools": ["issues.list"],
      "headers": {
        "Authorization": "Bearer <linear-api-key>"
      },
      "require_approval": "never"
    }
  ]
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'
This is the simplest flow. The model calls the allowed MCP tool and returns the final assistant message in one request. The response output array contains:
  1. function_call — the model’s call to the MCP-discovered tool
  2. function_call_output — the data returned by the MCP server
  3. message — the model’s text response summarizing the results

​
Require end-user approval

Set require_approval to 'always' when your app should stop and wait for an approval decision. In this flow, create the response in background mode, poll it, and look for an mcp_approval_request item in output. 
# Step 1: Create a background response with approval required
mka1 llm responses create --body '{
  "model": "auto",
  "instructions": "You are a project management assistant with access to Linear via MCP.",
  "input": "List my most recent Linear issue assigned to me.",
  "background": true,
  "store": true,
  "stream": false,
  "tools": [
    {
      "type": "mcp",
      "server_label": "Linear MCP",
      "server_url": "https://mcp.linear.app/mcp",
      "allowed_tools": ["issues.list"],
      "headers": { "Authorization": "Bearer <linear-api-key>" },
      "require_approval": "always"
    }
  ]
}'

# Step 2: Poll the response by id until an mcp_approval_request appears
mka1 llm responses get --response-id <response-id>

# Step 3: Send approval to continue
mka1 llm responses create --body '{
  "model": "auto",
  "previous_response_id": "<response-id>",
  "input": [
    {
      "type": "mcp_approval_response",
      "approval_request_id": "<approval-request-id>",
      "approve": true
    }
  ],
  "store": true,
  "stream": false
}'
If the end user denies the tool call, send approve: false. You can also include a reason field in the mcp_approval_response item. For approval UIs, show:
  • server_label — which MCP server is being used
  • name — which tool the model wants to call
  • arguments — what arguments it plans to send

​
MCP tool definition reference

ParameterTypeDefaultDescription
type"mcp"—Required. Identifies this as an MCP tool.
server_labelstring—Required. Display name for the MCP server.
server_urlstring—URL of the MCP server endpoint.
server_descriptionstring—Optional description of the server’s purpose.
allowed_toolsstring[]—Limit which tools the model can call.
headersobject—Headers to pass to the MCP server (e.g. auth tokens).
require_approval"always" | "never""always"Whether to pause for end-user approval before calling.
connector_idstring—Use a preconfigured connector instead of a custom server URL.
Credentials passed in headers are automatically masked in stored responses and streaming events.

​
Next steps