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

The MCP server package implements the server-side component of the Model-Context-Protocol, exposing Kaneo's internal functionality as standardized, reusable tools that external clients can discover and invoke via HTTP.

The packages/mcp directory in the usekaneo/kaneo repository contains the Model-Context-Protocol (MCP) server implementation that transforms Kaneo's task management features into interoperable tools. This package enables third-party clients, CLI tools, and automation scripts to interact with Kaneo's API through a standardized protocol interface rather than direct REST calls.

Core Architecture and Protocol Implementation

At the heart of the package, src/server.ts bootstraps an HTTP server that exposes the /mcp endpoint. This endpoint speaks the Model-Context-Protocol, handling standardized requests such as tools/list, tools/call, and register, along with OAuth-related authentication flows.

The server architecture separates concerns into distinct layers: protocol handling, tool execution, and authentication middleware. When an MCP-compatible client connects, it first negotiates capabilities through the tools/list method, which returns metadata about available tools defined in src/tools/*.ts.

Dynamic Tool Registration and Management

The package supports both built-in and dynamically registered tools. Built-in implementations like register and whoami reside in src/tools/*.ts and are automatically advertised to clients upon connection.

The src/tools/register.ts file implements the tools/register endpoint, allowing runtime registration of new tools without server restarts. This extensibility enables developers to treat Kaneo features as generic MCP tools that can be discovered programmatically.

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

// Initialise the client (points to the Kaneo MCP server)
const client = createMcpClient({ baseUrl: "http://localhost:3000/mcp" });

// Register a new tool called "hello"
await client.request("tools/register", {
  name: "hello",
  description: "Returns a friendly greeting",
});

Authentication and Security Infrastructure

The MCP server package includes a complete OAuth 2.0 device flow implementation to secure external access.

OAuth Device Flow Implementation

The src/auth/device-flow.ts module handles the OAuth device authorization grant flow, generating user codes and verification URIs that external clients use to authenticate. This allows CLI tools and headless applications to obtain tokens without embedded browsers.

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

const client = createMcpClient({ baseUrl: "http://localhost:3000/mcp" });

// Start the flow – gets a user-code & verification URL
const { userCode, verificationUri } = await client.request("oauth/start");

// Show the URL to the user, poll for token
const token = await client.pollForToken({ userCode });

Token Persistence and Validation

The src/auth/token-store.ts module persists issued access and refresh tokens while validating session identities. This store manages token lifecycles, ensuring that authenticated MCP sessions remain valid across tool invocations while supporting secure token refresh operations.

Client SDK and Programmatic Access

The src/kaneo/client.ts module provides a thin, typed wrapper around the MCP protocol. This client library abstracts the HTTP transport layer, encoding and decoding MCP requests so that consumers can call Kaneo's tools programmatically without handling raw protocol details.

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

const client = createMcpClient({ baseUrl: "http://localhost:3000/mcp" });

const result = await client.request("tools/call", {
  name: "whoami",
});

console.log(result); // → { userId: "...", email: "…" }

Installation and Configuration Utilities

The src/install/index.ts module handles server registration and configuration generation. It creates user-side mcp.json configuration files and merges server definitions, simplifying the process of connecting MCP clients to Kaneo instances.

The src/cli.ts file serves as the entry point for the kaneo-mcp command-line tool, exposing commands for installation, tool registration, and direct tool invocation. Together with the install/ directory utilities, these components provide a complete onboarding path for developers integrating Kaneo into their MCP workflows.

Summary

• src/server.ts runs the HTTP MCP server on /mcp, handling protocol requests and wiring authentication middleware.
• src/tools/*.ts defines built-in tools like whoami and register, with dynamic runtime registration supported via src/tools/register.ts.
• src/auth/device-flow.ts and src/auth/token-store.ts implement OAuth device flow and secure token persistence.
• src/kaneo/client.ts offers a typed client library for programmatic tool invocation.
• src/install/index.ts and src/cli.ts provide configuration management and command-line interfaces for client setup.

Frequently Asked Questions

What protocol does the Kaneo MCP server implement?

The server implements the Model-Context-Protocol (MCP), an open standard for exposing functionality as discoverable tools. It handles standardized methods including tools/list for discovery and tools/call for execution over HTTP.

How does authentication work when connecting to the MCP server?

The package uses OAuth 2.0 device flow implemented in src/auth/device-flow.ts. Clients request a user code and verification URI, the user authorizes the device through a browser, and the client polls for an access token stored securely in src/auth/token-store.ts.

Can developers add custom tools without modifying the server source code?

Yes. The tools/register endpoint defined in src/tools/register.ts allows runtime registration of new tools. External clients can register custom functionality dynamically, making the server extensible without restarts or redeployments.

Where does the CLI installer store configuration files?

The installation utilities in src/install/index.ts generate and manage mcp.json configuration files on the client side. These files contain server definitions and connection parameters required for MCP clients to locate and authenticate with the Kaneo MCP endpoint.

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