What Is the Purpose of the MCP Server in Kaneo?

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, 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.

# Start the stdio-based MCP server

npx kaneo-mcp serve

The CLI entry point in 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.

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

The HTTP routes are defined in 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, 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. 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:

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:

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.
• 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}