Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions content/blog/inkan-0-10.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
title: "Your API, as tools a model can call"
description: "inkan 0.10 serves every route as an MCP tool, made from the contract the route already has, and checks that what a model gets is what the docs say."
date: "2026-11-13"
author: "Vensin"
draft: true
---

Every inkan route carries its contract: what goes in, what comes out, and a few examples of
a call. Until now three readers used it: the validation, the docs page, and `inkan check`. In
0.10 there is a fourth. AI clients like Claude, Cursor or VS Code call tools over the
[Model Context Protocol](https://modelcontextprotocol.io), and a tool is, again, a name, a
description, an input schema and an output schema. inkan had all of that already.

```ts
const app = inkan({ title: "Tea Shop", version: "1.0.0", mcp: true });
```

That is the whole change to an app. Every documented route is a tool on `/mcp`.

## Nothing written twice

The tool's name is the route's `operationId`, the one `openapi.json` already has. Its
description is the summary, the description, and the examples, written as calls a model can
copy: `found: {"id":1} → 200`. The input schema is the params, query and body, the output
schema the 2xx answer. GET says it only reads; DELETE says it destroys. A route can rename or
reword its tool, or stay out with `mcp: false`, but it does not have to say anything.

Most ways of turning an API into MCP tools generate them from an OpenAPI file and then ask
you to curate the result. Here there is nothing to generate, so nothing goes stale.

## A tool call is a request

The part I care about most: a tool call does not have a way of its own into the app. A call
to `getTeasById` with `{ "id": 1 }` becomes `GET /teas/1`, with the caller's Authorization
header and cookies, and runs through the route's security, the hooks, the input checks,
middleware, `rateLimit` and the log like any request. Whatever the route would not let that
caller do, the tool cannot do either.

A problem comes back as a tool error with the problem as its text. When a model sends
`"id": "abc"`, it reads the same 400 a person would: which field, and what it should be. And
it can try again.

## Proven, not promised

`inkan check --mcp` runs every example a second time, as a tool call, and holds the answer to
the same contract. If the tool and the route ever disagree, the check says so before anyone
asks a model to use it.

I also tested the endpoint with the official MCP SDK and the new 2.x client, both the older
way (`initialize`) and the new stateless revision from July, 2026-07-28. That paid off right
away: the new client refused my first tool list because it had no cache hints, which the new
revision requires. It has them now.

## Locally too

`inkan mcp src/app.ts` serves the same tools on stdin and stdout, for clients that start a
server as a process. `-H "authorization: Bearer …"` hands it a token. The docs page got an
**mcp** button that copies the config a client needs.

## About speed

Without `mcp` nothing changes on the request path. While measuring I found that
`app.inject` had picked up an extra turn per request, and fixed it: the in-process bench is now
about 4 % faster than 0.9.4, almost all of it in `inject`, which only your tests use. The
numbers over the network are in the release notes.

## Next

MCP is experimental in 0.10, as WebSockets and jobs were at first. What comes after it is
still open: llms.txt next to the docs page, Standard Schema so a contract can be written in
Zod or Valibot, or `inkan mock`, a server made from the examples. Tell me which one you would
use first.

See you next time ✨
9 changes: 7 additions & 2 deletions content/docs/cli.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
title: "CLI"
description: "inkan check, diff, openapi, create, examples, hanko and seal."
description: "inkan check, diff, openapi, mcp, create, examples, hanko and seal."
---

```sh
npx inkan check src/app.ts [--only <text>] [--strict] [--format terminal|json|markdown]
npx inkan check src/app.ts [--only <text>] [--strict] [--mcp] [--format terminal|json|markdown]
npx inkan mcp src/app.ts [-H "name: value"]...
npx inkan openapi src/app.ts [-o openapi.json]
npx inkan routes src/app.ts
npx inkan diff openapi.json src/app.ts [--format terminal|json|markdown]
Expand All @@ -25,6 +26,10 @@ field that is required now, a value a request may no longer send, a value an ans
send now. Requests may only get looser and answers only stricter; it exits with `1` when
something breaks, so CI can ask for a major version.

`inkan mcp` serves the app as an [MCP](/docs/mcp) server on stdin and stdout, for clients
that start it as a process; `-H` sends a header with every tool call. `inkan check --mcp` runs
every example of a tool a second time, as a tool call.

`inkan create app` is what `npm create inkan` runs; its options are on
[Installation](/docs/installation#start-a-project). `inkan create plugin` writes a package for
a plugin of your own, see [Publish a plugin](/docs/publish-a-plugin).
Expand Down
164 changes: 164 additions & 0 deletions content/docs/mcp.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
---
title: "MCP"
description: "mcp: true: every route a tool for Claude, Cursor and other AI clients, made from the contract it already has."
---

<Callout title="New in 0.10.0, experimental">
The option, the tool shapes and the CLI may change in a minor release, named in the changelog.
</Callout>

The [Model Context Protocol](https://modelcontextprotocol.io) is how AI clients (Claude, Cursor,
VS Code and others) call tools. An inkan app already says, for every route, what goes in, what
comes out and what a call looks like. With `mcp: true` it says the same to those clients:

```ts
const app = inkan({ title: "Tea Shop", version: "1.0.0", mcp: true });
```

Every documented route is now a tool on `/mcp`, with nothing written twice. The tool is made
from the contract, and a tool call is a request to the route, so what a model gets is what the
docs page shows and `inkan check` tested.

## What a route becomes

```ts
app.get(
"/teas/:id",
{
summary: "One tea by its id",
params: t.object({ id: t.int() }),
response: { 200: Tea, 404: t.problem() },
examples: [
{ name: "found", params: { id: 1 } },
{ name: "missing", params: { id: 99 }, status: 404 },
],
},
handler,
);
```

```json
{
"name": "getTeasById",
"title": "One tea by its id",
"description": "One tea by its id\n\nExamples:\n- found: {\"id\":1} → 200\n- missing: {\"id\":99} → 404",
"inputSchema": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"], "additionalProperties": false },
"outputSchema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": ["id", "name"] },
"annotations": { "title": "One tea by its id", "readOnlyHint": true }
}
```

| | comes from |
| --- | --- |
| `name` | `mcp.name`, else the `operationId`, the same one `openapi.json` has |
| `description` | the summary, the description, and up to three examples written as calls |
| `inputSchema` | params and query side by side, declared `headers`, and `body`. Where a name is in both params and query, they go as `params` and `query` |
| `outputSchema` | the one 2xx answer, when it is a JSON object |
| `annotations` | the method: GET is read-only, DELETE destructive, PUT and DELETE idempotent |

`app.mcp()` hands back the tools and the routes that are none, with the reason:

```ts
const { tools, skipped } = app.mcp();
// skipped: [{ method: "GET", path: "/feed", reason: "answers with server-sent events" }]
```

WebSocket routes, event streams, raw, streamed and file bodies are no tools, and neither are
`hidden` routes. Two routes with the same tool name, or a name MCP cannot carry, throw when the
tools are made.

## A route's say

```ts
app.delete("/teas/:id", { /* … */ mcp: { name: "remove_tea", description: "Takes a tea off the shelf for good." } }, handler);
app.post("/admin/reset", { /* … */ mcp: false }, handler); // never a tool
```

`mcp: { name, description, annotations }` changes what the client is told; `annotations` is
merged over what the method says. `mcp: false` keeps a route out.

## A tool call is a request

A call to `getTeasById` with `{ "id": 1 }` is `GET /teas/1`, sent into the app as any other
request:

- **With the caller's credentials.** The Authorization header, cookies and an API key header the
MCP client sends go with it, and an API key a route reads from the query comes from the
endpoint's own URL. The route's `security`, your auth hooks and `@inkanjs/auth` decide, as
they would over HTTP.
- **Through everything.** Hooks, input checks, middleware, `bodyLimit`, `rateLimit` (once per
call) and the log, where it shows as `via MCP tool getTeasById`. The endpoint itself runs no
hooks: only the routes' requests do.
- **An answer is a result.** A 2xx is the tool's result, as JSON text and, with an
`outputSchema`, as `structuredContent` too. A problem is a tool error (`isError`) with the
problem as its text, so a model reads that `id` should have been an integer and tries again.
The status is in `_meta["dev.inkan/status"]`.

There is no second way into your app, and nothing a tool can do that the route would not let
the same caller do.

## Connecting a client

Over HTTP, give the client the endpoint. The docs page has an **mcp** button that copies this:

```json
{ "mcpServers": { "tea-shop": { "type": "http", "url": "http://localhost:3000/mcp" } } }
```

Or let the client start the app as a process and talk to it on stdin and stdout, with no
server running:

```sh
inkan mcp src/app.ts
inkan mcp src/app.ts -H "authorization: Bearer $TEA_TOKEN"
```

```json
{ "mcpServers": { "tea-shop": { "command": "npx", "args": ["inkan", "mcp", "src/app.ts"] } } }
```

`-H` sends a header with every call, such as the token a route asks for. What the app logs
goes to stderr, so stdout carries only the protocol.

## Proven by check

```sh
inkan check src/app.ts --mcp
```

Every example of a route that is a tool runs twice, once as a request and once as a
`tools/call`, and both answers are held to the same contract. `app.check({ mcp: true })` does
the same in a test.

```text
GET /teas/:id
✓ found 200 1.3ms
✓ missing 404 0.4ms
✓ found via MCP 200 0.3ms
✓ missing via MCP 404 0.2ms
```

## The endpoint

```ts
inkan({ mcp: { path: "/mcp", origins: ["https://claude.ai"], instructions: "Teas, their kinds and stock." } });
```

| option | |
| --- | --- |
| `path` | where it lives. Default `/mcp` |
| `origins` | the pages that may call it from a browser: by default the app's own origin, and clients without an Origin header, which are not browsers. Another origin is a 403. Same shape as `cors` and `ws.origins` |
| `instructions` | what a model is told about the server as a whole. Default: the app's `description` |

It speaks MCP **2026-07-28**, stateless, with every request's `MCP-Protocol-Version`,
`Mcp-Method` and `Mcp-Name` headers checked against its body, `server/discover`, and cache hints
on the tool list (`cacheScope: "public"`, `ttlMs` 0 in development, five minutes otherwise).
For older clients it answers `initialize` for 2025-11-25 back to 2025-03-26, without a session
either way. It takes POST only and one message per request. It is tested against the official
SDK 1.32 and `@modelcontextprotocol/client` 2.4, both the legacy way and pinned to 2026-07-28.

Without `mcp` there is no endpoint, and the request path does no more work than before.

Not there yet: resources and prompts, OAuth protected resource metadata (RFC 9728) for
clients that sign in by themselves, and `ctx.mcp`, for a handler to know it was called as a
tool. That name is reserved and arrives in a later release.
1 change: 1 addition & 0 deletions content/docs/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"storage",
"runtime",
"client",
"mcp",
"middleware",
"hooks",
"plugins",
Expand Down
Loading