# MCP Pulse — shareable MCP + usage analytics

Platform to **share an MCP server with clients**, store everything in **PostgreSQL**, and see **which users you have** and **which tools they use most**.

## What you get

| Piece | Role |
|--------|------|
| **Postgres** | Users, API keys, every tool call |
| **MCP endpoint** (`/mcp`) | What you give clients (HTTP + API key) |
| **Admin dashboard** | Users, top tools, recent activity |
| **Admin API** | Create users, rotate keys, suspend access |

## Quick start

```bash
# 1. Start Postgres
npm run db:up

# 2. Install deps
npm install

# 3. Migrate + seed demo clients
npm run db:migrate
npm run db:seed

# 4. Run platform (dashboard + MCP)
npm run dev
```

Open **http://localhost:3847**

- Admin token (default): `change-me-admin-token` (set in `.env` as `ADMIN_TOKEN`)
- Paste that token in the left sidebar and click **Save**

## Share MCP with a client

1. Open **Share MCP** (or **Users → Add user**)
2. Create a client — you get a one-time API key `mcp_...`
3. Send them a config like:

```json
{
  "mcpServers": {
    "shared-mcp-platform": {
      "url": "http://YOUR_HOST:3847/mcp",
      "headers": {
        "Authorization": "Bearer mcp_THEIR_KEY"
      }
    }
  }
}
```

Every tool call is logged to Postgres under that user.

## Built-in demo tools

- `whoami` — client profile
- `echo` — connectivity check
- `summarize_text` — short bullet summary
- `lookup_record` — sample ORD/CUS lookup
- `search_docs` — tiny docs search

Replace or extend tools in `src/mcp/create-server.ts`.

## Stdio mode (local Cursor)

For a single local key:

```bash
set MCP_API_KEY=mcp_...
npm run dev:mcp
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "shared-mcp-platform": {
      "command": "npx",
      "args": ["tsx", "src/mcp/stdio.ts"],
      "env": {
        "DATABASE_URL": "postgresql://mcp:mcp_secret@localhost:5432/mcp_usage",
        "MCP_API_KEY": "mcp_..."
      }
    }
  }
}
```

## Environment

Copy `.env.example` → `.env`:

| Variable | Purpose |
|----------|---------|
| `DATABASE_URL` | Postgres connection string |
| `PORT` | HTTP port (default `3847`) |
| `ADMIN_TOKEN` | Dashboard / admin API auth |
| `MCP_PUBLIC_URL` | URL shown in share snippets |

## Admin API (examples)

```bash
curl -H "X-Admin-Token: change-me-admin-token" http://localhost:3847/api/stats
curl -H "X-Admin-Token: change-me-admin-token" http://localhost:3847/api/users
```

## Project layout

```
src/
  db/          schema, migrate, seed, queries
  mcp/         MCP server (HTTP + stdio) + tools
  api/         admin REST API
  server.ts    dashboard + MCP host
public/        admin UI
```

## Production notes

- Change `ADMIN_TOKEN` and Postgres password before exposing publicly
- Put TLS in front (nginx/Caddy) and set `MCP_PUBLIC_URL` to `https://...`
- API keys are stored hashed (SHA-256); plaintext is only shown at create/rotate time