pivotkit-mcp¶

pivotkit-mcp is an MCP server: an AI client (Claude Code, Claude Desktop, VS Code and others) uses it to build pivot reports over data the operator names. The model never reads the data itself. It sees what the operator allows of each source (by default names, types and counts), writes a view, lets the server check it, and has the report written into a file or made into a link for the person who asked.

To set it up step by step, see Getting started: MCP server. This page is the reference.

npx -y pivotkit-mcp --source sales=sales.csv --output reports     # stdio, for a local client
npx -y pivotkit-mcp --config pivotkit-mcp.json --http             # Streamable HTTP on 127.0.0.1:3333

Node 22 or later. It brings the official MCP TypeScript SDK (@modelcontextprotocol/server, which speaks the protocol revision 2026-07-28 and the 2025 revisions) and pivotkit-server, which holds what it shares with the REST service (sources, policy, workers, output, sign-in) and brings pivotkit-report, pivotkit-cli's file handling, pivotkit-xlsx, ECharts 6.1.0 and jose (for OAuth). pivotkit-server serve runs this endpoint and the REST service on one port.

Tools¶

Every tool has an input and an output JSON Schema (draft 2020-12) and returns its result as structured content and as one text block: a short sentence with counts and ids (never a name or value from the data), then the JSON. A view with errors is not a tool error: ok or valid is false and findings say what to fix. The tools are one table shared with the command line (pivotkit-report/operations); the REST service offers the same operations with the same policy to programs.

The server also gives the model short instructions when it connects, a prompt pivotkit_report (for clients with a prompt picker) and a skill (see the skill).

What a source is¶

source is either the id of a source the operator configured (sales) or, when the operator allows files, file: and a path inside the allowed directories (file:q3.csv, file:/srv/reports/q3.csv). A relative path is looked up in each allowed directory in turn. Formats: CSV, TSV, TXT, JSON and XLSX, read as the command line reads them.

A file: path to the file of a configured source is that source: its scopes and its policy hold. The output directory may not lie inside an allowed directory (nor hold one), so the model cannot read back a report it was not shown. Put only data files into an allowed directory: the first line of any CSV, TSV, TXT or JSON file there becomes field names, which the model sees at every level.

A file named by file: is checked on its real path (symbolic links and .. resolved) against the allowed directories, then opened once without following a link at its end and checked again on the open file. A file with a second name (a hard link) is refused unless files.hardLinks is true. A file that is missing, outside the directories or replaced while it is read gets the same answer, FILE_NOT_AVAILABLE, so a model cannot probe which files exist elsewhere.

Exposure policy¶

The operator sets, per field, how much of it the model may see. A source's policy goes over the server's policy; field names are matched without regard to case.

A profile (policy.profiles.<name>, a policy of the same shape) gives one caller more or less than this: bound to a static token (auth.tokens[].profile), an OAuth client (auth.clientProfiles) or scope (auth.scopeProfiles), laid over each source's policy; a field a source hides stays hidden in every profile, and a caller without a profile gets the server's policy. See profiles.

A view that uses a field the model may not see in full (rows, columns, values, filters, sorting, a date grouping's source field) has its result withheld: render_view writes the file and returns its name, withheld: ["rows", "columns", "bytes", "content"] and a message for the user, but no count, size or content, since even a row count could answer "is this person in the data?".

suggest_view reads only what is not hidden. Its draft and picks name fields, never values or counts; the one thing they tell about a field's values is the date grouping its span gives (a span of up to two years is grouped by month), as a layout with a date on an axis does.

Configuration¶

The runner reads a configuration file (JSON) and its flags; a flag wins, and a list given as flags adds to the file's. Paths in the file are relative to the file. The configuration is read at start: a change needs a restart, except token files (read on every request). An unknown key or value is an error that names the key and the one probably meant.

The same file configures pivotkit-server, which reads rest.* and http.enable too; pivotkit-mcp ignores them.

{
  "sources": {
    "sales": {
      "file": "data/sales.csv",
      "title": "Sales",
      "description": "Orders since 2024, one row per order line",
      "link": "https://reports.example.com/sales",
      "policy": { "fields": { "Region": "show", "Product": "show", "Customer": "hide" } }
    }
  },
  "output": { "dir": "reports" },
  "policy": { "default": "summary", "items": 20 }
}

As a library (the SDK's stdio entry is serveStdio from @modelcontextprotocol/server/stdio):

import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { createMcpContext, listen } from "pivotkit-mcp";

const context = await createMcpContext({ sources: { sales: { load: async () => rows, version: () => rowsVersion } }, output: { dir: "/srv/reports" } });
serveStdio((ctx) => context.server(ctx));                               // stdio
// or HTTP with every check of this page, on node:http:
const server = await listen({ sources: { sales: { file: "/srv/data/sales.csv" } }, http: { port: 3333 } }, { env: process.env, stderr: process.stderr });

createMcpContext(options) checks the options (validateOptions), resolves the directories and starts the workers; context.server(ctx) builds a fresh McpServer for the SDK's serveStdio or createMcpHandler; await createHttpHandler(context) gives { fetch, close } with every check of this page; loadConfig(file) reads a configuration file into options. A library host may give a source load: async () => rows (rows or columnar data) and version: () => key instead of file; such sources run in the host's thread, not in a worker. createHttpHandler(context, { env }) reads static tokens from env (default process.env). pivotkit-mcp/policy exports the exposure policy (resolvePolicy, levelOf, exposeSource, exposeFindings, touchesClosed) for another front end over the same sources; it is pivotkit-server/policy under another name.

Limits and errors¶

Views from the model are checked with pivotkit-core's limits for views from outside (outsideLimits), data with its limits; the server's own default for files is 50 MiB (fileBytes, unpackedBytes). A call's input may hold at most 10,000 array elements and object members; an HTTP body at most 2 MiB.

A tool error is a result with isError and the text CODE: message (an input the tool's schema refuses is answered by the SDK before the tool runs, as Input validation error: ...); the message names a file by its base name only and holds no file content.

Logging¶

One JSON line per event on stderr (on stdio, stdout is the protocol): started (version, transport, address, auth mode, the number of sources, whether files and an output directory are on), call (tool, source id or the base name of a file, client, ok, error code, time in ms), refused (an HTTP request refused by the Host, Origin or token check, with its status) and warning. The client is the static token's name or the OAuth token's client id, never the person's id. No line holds a view, a value, a token or a full path. The log is the supervisor's to keep and rotate.

Streamable HTTP¶

--http serves the MCP endpoint at /mcp (POST; GET and DELETE as the SDK answers them), with these checks in order:

1. Host: only the localhost names, the public URL's host and --allow-host (protection against DNS rebinding, as the transport spec asks). It cannot be switched off.
2. Origin: a request with an Origin header (a browser) is refused with 403 unless its host name is in --allow-origin; a client that sends none (every non-browser client) passes.
3. Authentication for /mcp (below).

Host, Origin, the declared size and the token are checked from the headers before the body is read; at most 256 connections are open at once, and a request has 30 seconds. On SIGTERM the server takes no new connection and lets running requests finish for up to http.graceMs.

Without authentication: /healthz ({ "ok": true }, for a supervisor or a proxy), the OAuth discovery documents, and the quick-start page at /: what the server is, its endpoint, client configurations to copy, the auth mode and the tools. A browser that opens /mcp is sent there. The page lists source ids only when http.page.sources is true (default only with auth none), and only sources without scopes, never paths, fields or data; it loads nothing from elsewhere and has no script (Content-Security-Policy: default-src 'none').

The server listens on 127.0.0.1 unless --host says otherwise, and refuses another address without authentication unless --allow-unauthenticated says the network is trusted. There are no sessions: every request gets a fresh server from the shared context. Behind a reverse proxy: keep the server on 127.0.0.1 when the proxy runs on the same machine, terminate TLS at the proxy, forward /mcp, /.well-known/ and /, keep the Host header (or add the proxy's name with --allow-host), set --public-url, and turn response buffering off for /mcp. The server reads no X-Forwarded-* header: client addresses are in the proxy's log. For nginx:

location ~ ^/(mcp|\.well-known/|healthz$|$) {
    proxy_pass http://127.0.0.1:3333;
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_read_timeout 60s;
}

Authentication¶

Static tokens¶

The token comes from $PIVOTKIT_MCP_TOKEN, or several named tokens from auth.tokens, each from an environment variable or a file (read on every request, so a token is rotated without a restart), each with its own scopes (a token without scopes holds every scope). A token has at least 32 characters; make one with node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))". Tokens are compared as SHA-256 digests in constant time, never logged, and refused in the address (?access_token=) and when a request carries two Authorization headers. The token's name is the client in the log.

{ "auth": { "mode": "token", "tokens": [
    { "name": "analysts", "env": "PIVOTKIT_TOKEN_ANALYSTS", "scopes": ["sales", "hr"] },
    { "name": "viewers", "file": "/run/secrets/pivotkit-viewers", "scopes": ["sales"] } ] } }

OAuth 2.1¶

The server follows the MCP authorization spec (revision 2026-07-28) as a protected resource:

• It serves Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource/mcp, naming the issuer as its authorization server, and the issuer's own metadata at /.well-known/oauth-authorization-server for older clients.
• A request without a valid token gets 401 with WWW-Authenticate: Bearer resource_metadata="..." scope="..."; a token without the required scopes gets 403 insufficient_scope naming every scope the call needs.
• An access token must be a JWT signed by a key of the issuer's JWKS (RS256, PS256, ES256 or EdDSA by default; never none, never HMAC), with this issuer, an audience of this server (the resource, RFC 8707) or one of audience, and an expiry; 30 seconds of clock difference are allowed. Why a token failed stays on the server. The token is never passed on.
• At start the server reads the issuer's metadata (RFC 8414, then OpenID Connect discovery; its issuer must match exactly, its jwks_uri must be on the issuer's origin unless jwksUri is set), with a time limit and no redirects. Until it has it, /mcp answers 503 and the server keeps trying. Keys are fetched from the JWKS and kept for 10 minutes; a new key is fetched at most every 30 seconds. A token stays valid until it expires (no revocation check).

A token stays valid until it expires: keep the provider's access token lifetime short (minutes), so taking a person's access away takes effect soon. Set requiredScopes, so not every token the provider issues for this audience works, and requireTyp: "at+jwt" where the provider marks its access tokens so (RFC 9068), so an ID token is refused. Why a token was refused is logged with --log debug (jose's reason and the claim, never the token); the client is the token's azp or client_id (client when it has neither).

Opaque tokens (checked by introspection) are not supported: the provider must issue JWT access tokens. How a client registers (Client ID Metadata Documents, a pre-registered client or Dynamic Client Registration) is between the client and the provider: the provider needs a public client with PKCE, the scopes, and an audience the server accepts.

Examples (the issuer's form and what lands in aud differ by provider and setting: check them in your provider's documentation and in a decoded access token of your own):

{ "auth": { "mode": "oauth",
    "issuer": "https://auth.example.com/application/o/pivotkit/",
    "resource": "https://reports.example.com/mcp",
    "audience": ["<the provider's client id>"],
    "requiredScopes": ["pivotkit"] } }

{ "auth": { "mode": "oauth",
    "issuer": "https://login.example.com/realms/example",
    "resource": "https://reports.example.com/mcp",
    "requiredScopes": ["pivotkit"] } }

{ "auth": { "mode": "oauth",
    "issuer": "https://login.microsoftonline.com/<tenant id>/v2.0",
    "resource": "https://reports.example.com/mcp",
    "audience": ["api://<application id>", "<application id>"],
    "requiredScopes": ["Reports.Read"] } }

The skill¶

skills/pivotkit-reports/SKILL.md in the package teaches a model the workflow: describe the source, write a view from its fields, validate and use the suggestions, render or link, and what level and withheld mean. The server offers it as MCP skills to clients that support them, as the prompt pivotkit_report, and in short as its instructions. For clients that read skill folders, see Getting started.

Security¶

See Security: the MCP server for what the server protects against and what it does not.