# KYA-OS MCP Server

A ready-to-deploy [Model Context Protocol](https://modelcontextprotocol.io) server, protected by
[KYA-OS Checkpoint](https://kya.vouched.id). Deploy it in one click, point an MCP client at it, and
every agent that connects is verified by the KYA-OS detection engine — running in-process, no
gateway round-trip — before it can reach your tools.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fkya-os%2Fmcp-server-template&project-name=kya-os-mcp-server&repository-name=kya-os-mcp-server&demo-title=KYA-OS%20MCP%20Server&demo-description=A%20ready-to-deploy%20MCP%20server%20protected%20by%20KYA-OS%20Checkpoint&env=CHECKPOINT_PROJECT_ID,CHECKPOINT_API_KEY&envDescription=Your%20Checkpoint%20project%20id%20and%20a%20project%20API%20key%20—%20both%20on%20the%20project%20settings%20page&envLink=https%3A%2F%2Fkya.vouched.id)
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https%3A%2F%2Fgithub.com%2Fkya-os%2Fmcp-server-template)

> **Railway:** a one-click button is coming — Railway deploys published templates by code
> (`railway.com/new/template/<code>`), so it needs this repo published as a Railway template first.
> For now, deploy it on Railway from the repo directly (New Project → Deploy from GitHub repo).

## What you get

- **A working MCP server** at `/api/mcp` (streamable HTTP) with two example tools — swap in your own.
- **Checkpoint protection** via `withCheckpoint` from `@kya-os/checkpoint-nextjs` — the Rust
  detection engine runs in-process (WASM), and enforcement is driven by your dashboard policy.
- **Zero-config deploy** — a standard Next.js 16 App Router app; Vercel / Railway / Netlify detect
  and build it automatically.

## One-click deploy

1. Click a **Deploy** button above.
2. When prompted, paste two values from your [Checkpoint project settings](https://kya.vouched.id):
   - `CHECKPOINT_PROJECT_ID` — binds this server to your project's policy.
   - `CHECKPOINT_API_KEY` — authenticates the policy fetch.
3. Deploy. Your MCP endpoint is live at `https://<your-deployment>/api/mcp`.

> Secrets are entered on the platform, never in a URL. Without them the server still runs, using
> the engine's default detection instead of your dashboard policy.

## Connect an MCP client

Point any MCP client at your endpoint. For example, in a client that uses `mcp.json`:

```json
{
  "mcpServers": {
    "kya-os": {
      "url": "https://<your-deployment>/api/mcp"
    }
  }
}
```

Then call the `checkpoint_status` tool to confirm which project is protecting the server.

## Local development

```bash
cp .env.example .env.local   # add your CHECKPOINT_* values
npm install
npm run dev                  # http://localhost:3000  ·  MCP at /api/mcp
```

## How Checkpoint protects it

`middleware.ts` wires `withCheckpoint` across every route (including `/api/mcp`). The engine
verifies each request locally and applies your project's policy — block, challenge-for-delegation,
or observe — which you configure in the dashboard. Because verification is in-process, there's no
per-request network hop.

```ts
// middleware.ts
import { withCheckpoint } from '@kya-os/checkpoint-nextjs';

export default withCheckpoint({
  tenantHost: process.env.CHECKPOINT_TENANT_HOST ?? 'localhost:3000',
  projectId: process.env.CHECKPOINT_PROJECT_ID,
  apiKey: process.env.CHECKPOINT_API_KEY,
});
```

## Add your own tools

Tools live in `app/api/[transport]/route.ts`. Each `server.tool(...)` becomes callable by any
connected MCP client:

```ts
server.tool(
  'get_weather',
  'Return the current weather for a city.',
  { city: z.string() },
  async ({ city }) => ({
    content: [{ type: 'text', text: `It's sunny in ${city}.` }],
  })
);
```

## Going further — verifiable agent delegation

This template uses Checkpoint's **detection** layer. If you want agents to present a
cryptographically **verifiable, capability-scoped delegation** (a user grants an agent a
time-boxed, read-vs-write-separated credential from their own passkey-backed identity), see the
[Hobbsidian](https://github.com/H0BB5/hobbsidian) reference app, which builds on `@kya-os/id` and
`@kya-os/mcp`.

## Learn more

- Checkpoint dashboard & docs — [kya.vouched.id](https://kya.vouched.id)
- Model Context Protocol — [modelcontextprotocol.io](https://modelcontextprotocol.io)