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 the Agents API with MCP Vault when you want reusable agents that can call tools from an external MCP server. The vault keeps MCP server configuration and credentials outside the agent definition, so your app can rotate credentials without editing every agent. API Reference:

​
1. Register the MCP server

Create the MCP server once for the integration you want the agent to use. Use allowed_tools to expose only the tools the agent needs. Use require_approval when your product should ask the end user before the MCP tool runs. 
mka1 llm mcp-vault create-server --body '{
  "name": "Linear",
  "server_label": "linear",
  "server_url": "https://mcp.linear.app/mcp",
  "server_description": "Access Linear issues, projects, and comments.",
  "allowed_tools": ["issues.list", "issues.create", "comments.create"],
  "require_approval": "always",
  "metadata": {
    "integration": "linear"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'
The response includes a stable MCP server ID such as mcp_srv_.... Use that ID in agent tool definitions. See the Create MCP server API reference for the complete schema.

​
2. Store the MCP credential

Create a credential under the MCP server. The credential can use a bearer token, an authorization header value, custom headers, or no auth. Store end-user credentials with X-On-Behalf-Of so each end user gets isolated access. 
mka1 llm mcp-vault create-credential \
  --server-id mcp_srv_123 \
  --body '{
    "name": "Personal Linear token",
    "auth_type": "bearer",
    "bearer_token": "<linear-api-key>"
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'
The response includes a credential ID such as mcp_cred_.... Secret values are stored by the vault and are not returned in later list responses. Use List MCP credentials when your app needs to show saved credential metadata.

​
3. Test the server

Test the server before you attach it to an agent. This catches bad URLs and tool discovery problems early. The response reports whether the server connected and which tools were discovered. 
mka1 llm mcp-vault test-server \
  --server-id mcp_srv_123 \
  -H 'X-On-Behalf-Of: <end-user-id>'
See the Test MCP server API reference for request and response details.

​
4. Create the agent

Add an MCP tool to the agent with type: "mcp". Reference the vault records with mcp_server_id and mcp_credential_id. You can narrow the agent’s access further with allowed_tools on the tool definition. 
mka1 agents create --body '{
  "name": "linear-triage-agent",
  "description": "Triages Linear issues and drafts updates.",
  "model": "auto",
  "instructions": "Use Linear through MCP when the user asks about issue triage. Confirm before creating or editing external records.",
  "tools": [
    {
      "type": "mcp",
      "mcp_server_id": "mcp_srv_123",
      "mcp_credential_id": "mcp_cred_123",
      "allowed_tools": ["issues.list", "comments.create"],
      "require_approval": "always"
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "metadata": {
    "team": "support"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'
See the Create an agent API reference for every saved agent field.

​
5. Run the agent

Run the saved agent with the task-specific input. The agent reuses the saved MCP configuration and credential reference. 
mka1 agent-runs create \
  --agent-id agt_123 \
  --body '{
    "input": "Find my five newest bug issues and draft a short triage summary.",
    "metadata": {
      "source": "docs-recipe"
    }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'
Use Retrieve an agent run to poll status. Use Stream agent run events when your UI should show tool calls and partial progress.

​
Operational notes

  • Keep server-level allowed_tools broad enough for the integration and tool-level allowed_tools as narrow as the agent’s job allows.
  • Prefer require_approval: "always" for tools that mutate external systems.
  • Rotate a credential by creating a new MCP credential and updating the agent’s MCP tool to reference the new mcp_credential_id.
  • Delete credentials with the Delete MCP credential endpoint when an end user disconnects an integration.