MCP Integration¶

Aksara can expose your models and routes as MCP-compatible tools without a second service or a hand-written tool manifest. When your app is running, the tool catalog is available at /ai/tools/mcp and the generic JSON export remains available at /ai/tools.

What MCP Gets You¶

The MCP export turns the same metadata Aksara uses for Studio and AI flows into a format that MCP-aware clients can consume directly. That means an agent can discover tool names, read descriptions, inspect JSON schemas for inputs, and understand which tools are read-only versus write-capable.

Use the MCP endpoint when you want an external AI client to work against your live Aksara app instead of a copied prompt or static schema dump.

Quick Start¶

Start your app:

aksara dev

Open the MCP export in your browser or with curl:

curl http://127.0.0.1:8000/ai/tools/mcp

You will receive a response shaped like this:

{
  "tools": [
    {
      "name": "list_tasks",
      "description": "List Task records",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "metadata": {
        "method": "GET",
        "path": "/api/tasks",
        "usage_kind": "read_only"
      }
    }
  ],
  "count": 1,
  "version": "0.4.0"
}

How Tools Are Derived¶

Aksara builds MCP tool definitions from the same application surface that powers the REST API and Studio. Models, viewsets, route metadata, permissions, and AI field annotations all affect what an external agent sees.

Specifically, any custom ViewSet method decorated with @action (which defaults to ai_exposed=True) is automatically parsed into an MCP tool. The AI registry uses the method's docstring for the tool's description and its type hints for the inputSchema.

That gives you one source of truth. You define a model once, register a viewset once, and Aksara can expose that capability through HTTP, Studio, and MCP without duplicating configuration.

AI Metadata Matters¶

The quality of the MCP export depends on the metadata attached to your fields and routes.

Use ai_description to make field purpose obvious to external agents. Use ai_sensitive=True to keep secrets and internal-only values out of exported context. Use ai_agent_writable=False when a field should be visible but never changed by an agent.

For route-level control, pair MCP exposure with Aksara's AI permissions and route hints so tool discovery stays aligned with your application's safety rules.

MCP vs Generic Tool Export¶

Use /ai/tools when you want Aksara's generic JSON representation of tool definitions. Use /ai/tools/mcp when the consumer expects MCP-shaped tools with inputSchema and transport metadata.

Both endpoints are derived from the same underlying tool registry, so the tool count and permissions stay in sync.