Mindset AI Sample MCP Server

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.