Content
# 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.
[](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)
[](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)
