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

> Discover the purpose of the MCP server package in Kaneo. Learn how it exposes Kaneo's functionality as reusable tools accessible via HTTP for external clients.

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

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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.

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/src/install/index.ts) module handles server registration and configuration generation. It creates user-side [`mcp.json`](https://github.com/usekaneo/kaneo/blob/main/mcp.json) configuration files and merges server definitions, simplifying the process of connecting MCP clients to Kaneo instances.

The [`src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/src/tools/register.ts).
- **[`src/auth/device-flow.ts`](https://github.com/usekaneo/kaneo/blob/main/src/auth/device-flow.ts)** and **[`src/auth/token-store.ts`](https://github.com/usekaneo/kaneo/blob/main/src/auth/token-store.ts)** implement OAuth device flow and secure token persistence.
- **[`src/kaneo/client.ts`](https://github.com/usekaneo/kaneo/blob/main/src/kaneo/client.ts)** offers a typed client library for programmatic tool invocation.
- **[`src/install/index.ts`](https://github.com/usekaneo/kaneo/blob/main/src/install/index.ts)** and **[`src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/src/install/index.ts) generate and manage [`mcp.json`](https://github.com/usekaneo/kaneo/blob/main/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.