@flink-app/mcp-plugin

Expose Flink AI tools as an MCP server so MCP clients — Claude Code, Claude Desktop, Cursor, custom agents — can call them over HTTP.

• Uses the Streamable HTTP transport (stateless, load-balancer friendly), mounted on the Flink app's own Express server.
• Tools are opt-in per tool via mcp: true.
• Every call runs inside Flink's request context: the authenticated user and permissions flow into tools exactly as for agents, and the tool's declarative permissions are enforced.

Install

pnpm add @flink-app/mcp-plugin

Usage

import { FlinkApp } from "@flink-app/flink";
import { mcpPlugin } from "@flink-app/mcp-plugin";

const app = await new FlinkApp<AppCtx>({
    name: "My app",
    auth: jwtAuthPlugin({ ... }),
    plugins: [
        mcpPlugin({
            instructions: "Tools for looking up cars in the demo inventory.",
        }),
    ],
}).start();

Mark the tools you want to expose:

export const Tool: FlinkToolProps = {
    id: "search-cars-by-brand",
    description: "Search for cars by brand name.",
    inputSchema: z.object({ brand: z.string() }),
    permissions: ["car:read"],
    mcp: true, // 👈 visible over MCP
};

Tools without mcp: true stay internal to your agents.

Title and annotations

MCP clients decide how much friction to put in front of a tool call based on its annotations. Without them a client has to assume the worst, so even a pure lookup gets an approval prompt on every call. Set them on the Tool props together with an optional human readable title:

export const Tool: FlinkToolProps = {
    id: "get-order-outcome",
    title: "Order outcome",
    description: "Returns what was done with an order. Read-only.",
    mcp: true,
    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
};

Both fields are passed through to tools/list as-is and omitted when not set. The hints are advisory: Flink does not enforce them, so a tool marked readOnlyHint: true that writes is the author's problem, as in the MCP spec. Agents ignore both fields.

Connecting from Claude Code

claude mcp add --transport http my-flink-app https://api.example.com/mcp \
  --header "Authorization: Bearer <token>"

Options

Authentication

Rejected requests get a 401 with WWW-Authenticate: Bearer (or the status of the returned FlinkResponse). Per-tool permissions are always enforced on top, using the permissions resolved by authentication.

How tool results map to MCP

Input schemas come from inputSchema (Zod 4), inputJsonSchema, or the compiler-generated schema — same priority as for agents. outputSchema is advertised when it describes an object.

Plugin context

ctx.plugins.mcp.listTools(); // McpToolDefinition[] currently exposed
ctx.plugins.mcp.path;        // "/mcp"

Notes

• Stateless transport: GET/DELETE on the endpoint return 405 (no sessions, no server-initiated notifications). This is what Claude Code and other current clients expect.
• Tool descriptions become the model's only documentation — make them explicit about arguments and side effects.
• Long-running tools must finish within the client's request timeout.