# What Is the Purpose of the MCP Server in Kaneo?

> Discover the MCP server's purpose in Kaneo. It securely bridges AI clients with Kaneo's API, translating natural language into authenticated API calls and respecting workspace permissions.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: internals
- Published: 2026-08-30

---

**The MCP server in Kaneo acts as a secure bridge between AI clients (such as Claude or Cursor) and Kaneo's project-management API, translating natural-language requests into authenticated API calls while respecting user workspace permissions.**

Kaneo is an open-source project management platform designed for modern teams. The repository `usekaneo/kaneo` includes a built-in MCP (Model Context Protocol) server that exposes the entire Kanban-style project management interface to AI agents, eliminating the need for custom integrations per client.

## Unified AI Interface for Project Management

The primary purpose of the MCP server is to provide a **single, standardized interface** between AI assistants and Kaneo's backend. Instead of building separate plugins for each AI product, the Kaneo MCP server implements the Model Context Protocol, allowing any MCP-compatible client to interact with workspaces, projects, and tasks using natural language.

In [`packages/mcp/src/server.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts), a factory function creates the server instance that handles protocol translation. This design centralizes the logic for converting MCP tool calls into HTTP requests against Kaneo's existing API endpoints, ensuring consistency across all AI interactions.

## Dual Transport Architectures

The Kaneo MCP server supports two distinct transport modes to accommodate different deployment scenarios, both instantiated from the same core factory.

### Stdio Mode for Local Agents

For desktop AI clients, the server runs as a **stdio process** through the `kaneo-mcp` CLI. This mode is ideal for local development or single-user setups where the AI tool spawns the server as a subprocess.

```bash

# Start the stdio-based MCP server

npx kaneo-mcp serve

```

The CLI entry point in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts) handles argument parsing and initializes the stdio transport, reading configuration from environment variables.

### HTTP Endpoint for Remote Agents

For remote agents or service-to-service communication, the server exposes an **HTTP endpoint** at `/mcp`. This allows cloud-hosted AI services to interact with Kaneo without requiring local installation.

```ts
// Programmatic HTTP server startup
const { createMcpServer } = require('@kaneo/mcp');
createMcpServer().listen(4000);

```

The HTTP routes are defined in [`apps/api/src/mcp/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/mcp/index.ts), which handles OAuth registration and authorization for the MCP endpoint, making it accessible to remote automation scripts.

## Permission-Aware Authentication

Security is enforced through Kaneo's standard API key system. Rather than requiring admin tokens, the MCP server uses **workspace-scoped API keys** bound to individual users.

In [`packages/mcp/src/server.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts), the server initializes with a Kaneo client that validates the API key from the `KANEO_API_KEY` environment variable or request headers. Every tool execution respects the user's workspace roles defined in `@kaneo/permissions`, ensuring AI agents cannot escalate privileges beyond the key holder's rights.

## Tool Catalog and Capabilities

The MCP server exposes Kaneo's functionality through a structured tool catalog registered in [`packages/mcp/src/tools/register.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/tools/register.ts). Available operations include:

- **Workspace and project management** – List and navigate organizational structures
- **Task lifecycle operations** – Create, read, update, and search tasks with full field support including status, assignee, and due dates
- **Workflow automation** – Move tasks between columns, manage labels, and create task relations
- **Collaboration features** – Add comments and log time entries against specific tasks

When an AI client invokes a tool, the server translates the MCP request into the corresponding Kaneo API call and returns structured data back to the agent.

## Deploying the Kaneo MCP Server

### Stdio Deployment

For local AI assistants like Claude Desktop:

```ts
import { createMcpClient } from "@kaneo/mcp";

const client = createMcpClient({
  command: "kaneo-mcp",
  env: { KANEO_API_KEY: "YOUR_WORKSPACE_API_KEY" },
});

// List tasks in a specific project
await client.call("listTasks", { projectId: "proj-123" });

```

### HTTP Deployment

For remote integration:

```ts
import axios from "axios";

const base = "http://localhost:4000/mcp";
const apiKey = "YOUR_WORKSPACE_API_KEY";

async function listProjects() {
  const resp = await axios.post(
    `${base}/listProjects`,
    { /* MCP protocol payload */ },
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );
  return resp.data;
}

```

## Summary

- The **MCP server in Kaneo** standardizes AI integration by implementing the Model Context Protocol, eliminating the need for custom connector development for each AI assistant.
- **Two transport modes**—stdio for local clients and HTTP for remote services—are both created by the factory function in [`packages/mcp/src/server.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts).
- **Authentication uses standard workspace API keys**, enforcing user-specific permissions through `@kaneo/permissions` without requiring elevated admin access.
- The **tool catalog** defined in [`packages/mcp/src/tools/register.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/tools/register.ts) exposes full project management capabilities, from task creation to time tracking, enabling comprehensive workflow automation.

## Frequently Asked Questions

### How do I start the MCP server in stdio mode?

Run the `kaneo-mcp` CLI package using npx: `npx kaneo-mcp serve`. This spawns the stdio server defined in [`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts), which reads your API key from the `KANEO_API_KEY` environment variable and communicates via standard input/output streams.

### Can I run the Kaneo MCP server as an HTTP service?

Yes. Import `createMcpServer` from `@kaneo/mcp` and call `.listen(port)` to expose the HTTP endpoint. The route handlers in [`apps/api/src/mcp/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/mcp/index.ts) manage OAuth and authorization for web-based AI agents, allowing remote services to connect securely.

### What permissions does the MCP server require?

The server requires a standard Kaneo API key generated from workspace settings. Because the key is bound to a specific user, all AI actions inherit that user's workspace roles defined in `@kaneo/permissions`. The server cannot access resources beyond what the key owner is permitted to view or modify.

### Which AI clients are compatible with Kaneo's MCP server?

Any client supporting the Model Context Protocol—such as Claude Desktop, Cursor, or custom MCP-compatible agents—can connect to Kaneo. Stdio mode works with local desktop applications, while HTTP mode enables integration with cloud-based services or custom automation scripts that follow the MCP specification documented in [`apps/site/lib/guides/project-management-mcp-ai-agents.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/site/lib/guides/project-management-mcp-ai-agents.ts).