Mindset AI — Sample MCP Server & Onboarding

A small, runnable example of an MCP (Model Context Protocol) server that connects to a Mindset AI agent. It calls only free public APIs (no keys, no customer data), so you can run it end-to-end immediately and use it as a reference for building your own.

New here? Read START_HERE.md first. It gives the global view of how a Mindset MCP server, agent, and widget fit together, then points you at the right files in order. It's written so a customer's AI coding agent can orient itself end-to-end.

In one sentence: this repo has 3 small tool servers (weather, profile, wikipedia) and one translator — mcp-http-server.js (npm run start:mcp) — that re-serves all 5 of their tools at a single /mcp endpoint in the language Mindset speaks (JSON-RPC + bearer auth + x-user-id headers). You give AMS that one URL; the stdio (start:weather) and legacy REST (start:http) runners are not Mindset-compatible.

The 3 sample servers (5 tools)

All three are exposed together, in a Mindset-compatible way, by the translator (npm run start:mcp). See START_HERE.md → "How this repo is wired".

Related MCP server: MCP Server Basic Example

Onboarding docs (in docs/)

The transport contract the Mindset agent speaks is in MINDSET_AI_COMPLIANCE.md. Canonical platform reference: https://docs.mindset.ai.

Quick start

npm install

# Start the Mindset-compatible server (the translator). Prints an API key on first run.
export MCP_API_KEY="$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")"
npm run start:mcp        # → http://localhost:8080/mcp

Smoke-test it:

# List tools (no user headers needed)
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool (tool execution requires the identity headers)
curl -s -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" -H "Content-Type: application/json" \
  -H "x-user-id: test-user" -H "x-app-uid: test-app" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_weather","arguments":{"location":"London"}}}'

Full walkthrough: docs/SETUP.md.

Testing

node test-mcp-compliance.js "$MCP_API_KEY"   # 10-point Mindset compliance suite
npx @modelcontextprotocol/inspector http://localhost:8080/mcp   # interactive MCP Inspector

There is also an interactive browser tester at public/test.html.

Other entry points (NOT Mindset-compatible)

These exist for local experimentation only — do not register them in AMS:

• npm run start:weather / start:wikipedia — single server over stdio (for Claude Desktop / MCP Inspector)

• npm run start:http — legacy plain-REST API

• npm run start:multi-mcp — the alternate TypeScript build under src/ (per-server /mcp/<name> endpoints)

For Mindset, always use npm run start:mcp.

License

See LICENSE.