MCP Server

The willaOS MCP server is available at:

https://os.willacreative.dev/api/mcp

It uses the Streamable HTTP transport and the same bearer API keys as REST.

Install

Add willaOS to an MCP client with an HTTP server entry:

{
  "mcpServers": {
    "willaos": {
      "url": "https://os.willacreative.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${WILLA_API_KEY}"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "willaos-local": {
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer ${WILLA_API_KEY}"
      }
    }
  }
}

Auth And RBAC

MCP tools call the same shared domain helpers and permission checks as REST. A tool may be present in the catalog but still return Forbidden for a key that lacks the corresponding route or field permission.

Use:

• Read-scoped keys for status, dashboard, and research agents.
• Write-scoped keys only for agents that have an explicit approval or human review workflow.
• Project/client-scoped user keys when an external collaborator should only see a subset of data.

Tool Catalogue

The generated tool catalogue is in MCP Tool Catalog. It is generated from app/api/mcp/route.ts and should be refreshed whenever new tools land.

Response Shape

Tools return MCP content blocks. willaOS serializes structured payloads as formatted JSON text:

{
  "content": [
    {
      "type": "text",
      "text": "{ \"data\": [] }"
    }
  ]
}

Tool-level failures return a text error block. Auth failures use Forbidden; unexpected server errors return a generic tool failure message and log server-side details.