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)

Server	Tools	Public API	Teaches
weather	get_weather	Open-Meteo	the simplest possible tool (one param) + the widget example
profile	get_my_profile	none (synthetic)	identity & security — reads x-user-id, takes no user_id parameter
wikipedia	search_wikipedia, get_wikipedia_article, get_wikipedia_summary	MediaWiki	a multi-tool search → detail flow

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".

Onboarding docs (in docs/)

Doc	Covers
SETUP.md	Run the server locally + smoke test
SECURITY.md	How the agent and server authenticate — bearer vs x-user-id, the identity headers, the never-trust-a-param rule
DEPLOYMENT.md	Ship to Cloud Run (public HTTPS URL for AMS)
AMS_CONFIGURATION_GUIDE.md	Register the server, create the agent, attach the widget
WIDGETS.md	The show_* widget mechanism (worked example: widgets/WeatherWidget.mdx)
MINDSET_API.md	Embed the agent in a page (SDK v3) + provision sessions (REST)

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.