Skip to main content
This gets you from zero to a first Intent Gap Report. You’ll run the mcpeye stack with Docker, wrap your MCP server with the TypeScript SDK, drive a little traffic, and read the report.
1

Bring up the stack

Clone the repo and start everything with Docker Compose. This launches Postgres, Redis, a one-shot migrate service that creates the schema, the ingest API (port 3001), the web dashboard (port 3000), and the summarizer worker.
git clone https://github.com/mcpeye/mcpeye.git
cd mcpeye
cp .env.example .env   # optionally set OPENAI_API_KEY or ANTHROPIC_API_KEY
docker compose up
The migrate service runs first and creates the schema automatically — no manual db:push or db:migrate. An LLM key is optional: ingest and session replay work without one; a key only powers the LLM summaries and the Intent Gap Report.The dashboard is now at http://localhost:3000 and the ingest API at http://localhost:3001.
2

Create a project

Open the dashboard and click Create your first project. You’ll get a project id and a one-time ingest secret — copy it now, it’s stored only as a hash and is never shown again. (Each project has its own secret; the SDK sends it to authenticate. There is no shared server-wide secret.)
curl -s -X POST localhost:3001/projects \
  -H 'content-type: application/json' \
  -d '{"name":"my-server"}'
# -> {"id":"...","ingestSecret":"..."}   (ingestSecret is returned exactly once)
3

Install the SDK

In the project that runs your MCP server:
npm install mcpeye
4

Wrap your MCP server

Point the SDK at your ingest API and wrap your server. The SDK injects the mcpeyeIntent parameter into every tool, captures each call, and ships batches to the API in the background.track() is the entire public API. Call it after registering your tools, passing the project id from the previous step:
import { track } from "mcpeye";
// after registering your MCP server's tools:
track(server, "your-project-id", {
  ingestUrl: process.env.MCPEYE_INGEST_URL ?? "http://localhost:3001",
  ingestSecret: process.env.MCPEYE_INGEST_SECRET,
});
Set the env vars in your instrumented server — MCPEYE_INGEST_SECRET is the per-project secret you copied when you created the project:
export MCPEYE_INGEST_URL="http://localhost:3001"
export MCPEYE_INGEST_SECRET="<the ingest secret from Create project>"
Using the high-level McpServer? Pass it directly — track() unwraps to its underlying low-level Server.
5

Drive some traffic

Connect an agent (Claude Desktop, your app, anything that speaks MCP) and let it use your tools the way real users do. Each call now arrives at the ingest API with the agent’s self-reported intent attached.
6

Read the Intent Gap Report

The worker sessionizes the calls and runs the LLM summary pass on a schedule. Open the dashboard, pick your project, and open the latest Intent Gap Report — the top asks your tools attempted but could not deliver, ranked, with example sessions to drill into.
Seeing entries under Attempted but failed? That’s the signal. Those are real user goals your server isn’t satisfying yet.

​
Next steps

Understand the Intent Gap Report

What it measures, and the one thing it honestly can’t see.

How it works end to end

From injected intent to ingest to report.

Self-hosting reference

Env vars, ports, and the privacy model.

Other SDKs

Python and Ruby servers too.