{
  "markdown": "# Squad MCP Server\n\n[![smithery badge](https://smithery.ai/badge/squadai/squad)](https://smithery.ai/servers/squadai/squad)\n\nA remote MCP server that brings [Squad](https://meetsquad.ai) — the AI product feedback intelligence platform — directly into your AI workflows. Connect Squad to Claude, ChatGPT, or any MCP-compatible AI assistant to turn raw user feedback into signals, insights, actions, and briefs without context switching.\n\nSquad continuously ingests feedback, clusters it into **signals**, distils it into **insights**, and links it to the **actions** and **goals** that move your product forward. The MCP server exposes that same intelligence — read the evidence behind a decision, capture new feedback, and generate briefs from your assistant.\n\n## 🚀 Quick Start\n\n### For Users\n\nConnect Squad to your AI assistant in seconds:\n\n**Claude Code:**\n\n```bash\nclaude mcp add --transport http squad https://mcp.meetsquad.ai/mcp\n```\n\nOn first use, you'll be prompted to authenticate via OAuth in your browser.\n\n**Other MCP Clients:**\n\nConnect using `https://mcp.meetsquad.ai/mcp` — OAuth configuration is automatically discovered via the server's `.well-known/oauth-protected-resource` metadata (which points clients at PropelAuth as the authorization server).\n\n## 📖 Usage Examples\n\nSee **[USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md)** for detailed real-world examples. A few things you can ask:\n\n- **Triage feedback** — \"Capture this support ticket in Squad and tell me if it's a known theme.\"\n- **Weekly review** — \"Run my weekly product review: what changed and what needs deciding?\"\n- **Ground the evidence** — \"Show me the customer signals behind insight IN-42.\"\n- **Draft a brief** — \"Generate a brief for action AC-12.\"\n- **Search everything** — \"Find all feedback related to onboarding friction.\"\n- **Ground a ticket** — \"Pull the customer evidence behind AC-7 before I build it.\"\n\nSquad entities are referenced by short **display IDs** so the assistant can cite its evidence:\n\n| Prefix | Entity          | Prefix | Entity            |\n| ------ | --------------- | ------ | ----------------- |\n| `SI-`  | Signal          | `GL-`  | Goal              |\n| `IN-`  | Insight         | `BR-`  | Brief             |\n| `AC-`  | Action          | `DC-`  | Document          |\n| `CL-`  | Cluster         |        |                   |\n\n## Tools\n\nThe server exposes 30 tools. Write tools require a token minted with the `write:workspace` scope; read tools only need `read:workspace`.\n\n- `list_workspaces` — List every organisation and workspace you can access, with the current selection marked.\n- `select_workspace` — Select which organisation and workspace subsequent tools operate on.\n- `get_workspace_overview` — One-call orientation: mission and description, top goals, recent signal activity, evidence-chain health, and open work counts.\n- `update_workspace` — Update the current workspace's name, description, mission statement or logo.\n- `list_members` — People in the current organisation with their user IDs.\n- `search` — Keyword search across signals, insights, actions, goals, documents and clusters.\n- `get_entity` — Fetch any entity by display ID (`SI-1`, `IN-1`, `AC-1`, `GL-1`, `BR-1`, `DC-1`, `CL-1`) or UUID. Also how you check on async work.\n- `list_signals` — Browse raw feedback signals with filters for source, type, sentiment, cluster and date range.\n- `find_similar_signals` — Semantically related signals for a given signal — \"has anyone else said this?\".\n- `list_clusters` — Browse signal clusters (recurring themes in feedback) with sizes and labels.\n- `get_cluster` — A cluster's label, stats, member signals and linked insights.\n- `list_insights` — Browse distilled insights ranked by combined score, with category/score/status filters or scoped to a goal.\n- `list_actions` — Ranked actions (what the evidence says to do next) filtered by status, assignee, priority or parent insight.\n- `get_action_context` — Everything needed to execute an action in one call: the action, the parent insight, the customer evidence behind it, and the goals it serves.\n- `update_action` — Edit an action's priority, effort, category or notes; assign it; or link it to an insight or brief.\n- `update_action_status` — Move an action through its lifecycle: start, complete, dismiss or snooze.\n- `list_goals` — Strategic goals ordered by importance.\n- `create_goal` — Create a strategic goal.\n- `update_goal` — Update a goal's title, description or importance.\n- `update_insight` — Curate an insight: set category or status, and link/unlink the goal it supports.\n- `dismiss_signal` — Permanently remove a signal from the workspace (noise, spam, or mis-ingested content).\n- `get_activity` — The workspace change feed (humans and Squad agents), newest first.\n- `list_documents` — Browse workspace knowledge documents (and briefs) with their paths and tags.\n- `create_document` — Create a knowledge document from markdown (research summaries, meeting notes, analyses).\n- `update_document` — Replace a document's markdown body and/or title, and manage tags.\n- `list_briefs` — Briefs with their status (building/draft/in_review/finalised/failed) and recommendation.\n- `generate_brief` — Kick off AI generation of a brief from an action or insight.\n- `update_brief_status` — Move a brief through its review lifecycle: draft, in_review, or finalised.\n- `ingest_signal` — Pipe user feedback into the evidence chain (1–50 items, deduplicated server-side).\n- `list_integrations` — Connected feedback sources for this workspace and their sync health.\n\n### Prompts\n\nReady-made workflows exposed as MCP prompts:\n\n- **`triage-feedback`** — check for duplicates, ingest a piece of feedback, and report where it landed.\n- **`weekly-product-review`** — what changed, what the evidence says, and what needs deciding.\n- **`draft-decision-brief`** — generate a brief from an action or insight and walk it to a readable draft.\n- **`ground-this-ticket`** — for coding agents: pull the customer evidence behind a piece of work before building it.\n\n### Resources\n\nPin these so strategy questions need no tool calls:\n\n- **`squad://workspace/context`** — the current workspace's mission and product context.\n- **`squad://goals`** — the workspace's strategic goals with importance rankings.\n\n### Tool Capabilities\n\n- ✅ Safety annotations (`readOnlyHint` / `destructiveHint`) on every tool\n- ✅ Structured Zod input schemas\n- ✅ User- and workspace-isolated data access via OAuth\n- ✅ Scope-gated writes (`write:workspace`)\n\n## 🏗️ Architecture\n\n```\n┌─────────────┐         OAuth          ┌──────────────┐\n│  Claude /   │ ◄────────────────────► │  PropelAuth  │\n│  ChatGPT    │    (Authentication)     │   (IdP)      │\n└─────────────┘                         └──────────────┘\n       │\n       │ HTTPS + Bearer Token\n       ▼\n┌──────────────────────────────────────────────┐\n│  Squad MCP Server                            │\n│  ┌────────────────────────────────────────┐  │\n│  │  OAuth → introspect + verify token     │  │\n│  │  JWT minting → service credentials     │  │\n│  │  Redis → workspace selection + tokens  │  │\n│  │  MCP handler → tools / prompts / res.  │  │\n│  │  PostHog → tool-call telemetry         │  │\n│  └────────────────────────────────────────┘  │\n└──────────────────────────────────────────────┘\n       │\n       │ Squad API Calls (minted JWT)\n       ▼\n┌──────────────┐\n│  Squad API   │\n└──────────────┘\n```\n\nThe server is built on [`mcp-use`](https://github.com/mcp-use/mcp-use) v2 and talks to the Squad platform API over **GraphQL**. Each request is served statelessly: the MCP layer holds no session, and every call re-introspects its own bearer token. **Redis** stores the durable per-user state (workspace selection and minted-token cache), so any instance can serve any request. Backend types are generated from a committed GraphQL schema snapshot (see [GraphQL codegen](#graphql-codegen)).\n\n## 🛠️ Development\n\nThis repository contains the source code for the Squad MCP remote server.\n\n### Prerequisites\n\n- Node.js 22+\n- pnpm\n- Nix (optional, for a reproducible dev environment via `flake.nix`)\n- PropelAuth credentials (OAuth 2.1 client + backend API key)\n- Redis (optional locally; workspace selection falls back to in-memory)\n\n### Local Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/the-basilisk-ai/squad-mcp.git\ncd squad-mcp\n\n# Install dependencies\npnpm install\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your PropelAuth credentials (and SQUAD_ENV=dev to target the dev platform)\n\n# Start development server with hot reload\npnpm dev\n\n# Server available at http://localhost:3232\n```\n\n### Environment Variables\n\n| Variable                                                          | Required | Purpose                                                        |\n| ----------------------------------------------------------------- | -------- | -------------------------------------------------------------- |\n| `PROPELAUTH_CLIENT_ID` / `PROPELAUTH_CLIENT_SECRET`               | ✅       | OAuth 2.1 client credentials for token introspection           |\n| `PROPELAUTH_API_KEY`                                              | ✅       | Backend integration key for minting service JWTs               |\n| `SQUAD_ENV`                                                       |          | `dev` or `production` (default `production`) — selects auth/API/app URLs |\n| `PORT` / `MCP_URL` / `BASE_URI`                                   |          | Server port and externally-advertised base URL                 |\n| `REDIS_URL`                                                       |          | Redis connection for deploy-safe workspace selection and token cache (in-memory if unset) |\n| `SQUAD_GRAPHQL_URL`                                               |          | Override the Squad GraphQL endpoint (also used by codegen)     |\n| `POSTHOG_API_KEY` / `POSTHOG_HOST`                                |          | Enable tool-call telemetry                                     |\n| `LOG_LEVEL`                                                       |          | Logger verbosity                                               |\n\n### Available Commands\n\n```bash\npnpm dev                # Start dev server with hot reload (mcp-use)\npnpm build              # Build the server (mcp-use)\npnpm start              # Start the built server\npnpm deploy             # Deploy via mcp-use\npnpm test               # Run unit tests (vitest)\npnpm format             # Lint/format check (biome)\npnpm format:fix         # Auto-fix lint/format issues\npnpm codegen            # Regenerate GraphQL types from schema.graphql\npnpm codegen:check      # Fail if generated GraphQL types are stale\n```\n\n### Testing the Server\n\n```bash\n# Check health\ncurl http://localhost:3232/health\n\n# Check OAuth discovery\ncurl http://localhost:3232/.well-known/oauth-protected-resource\n\n# Test with the built-in inspector\npnpm dev   # then open the inspector and connect to http://localhost:3232/mcp\n```\n\n### Project Structure\n\n```\nsquad-mcp/\n├── server.ts                   # MCP server entry point (OAuth, tool/prompt/resource registration)\n├── server.json                 # MCP registry metadata (see MCP_REGISTRY.md)\n├── schema.graphql              # Committed snapshot of the Squad platform GraphQL schema\n├── codegen.ts                  # GraphQL Code Generator config\n├── src/\n│   ├── tools/                  # Tool implementations, grouped by surface\n│   │   ├── registry.ts         # Single registration path (annotations, errors, telemetry)\n│   │   ├── workspace.ts        # list/select workspaces, overview, members\n│   │   ├── search.ts           # semantic search\n│   │   ├── get-entity.ts       # fetch any entity by display ID / UUID\n│   │   ├── evidence.ts         # signals, clusters, insights\n│   │   ├── actions-read.ts     # list actions, action context\n│   │   ├── actions-write.ts    # update actions + status\n│   │   ├── strategy-read.ts    # goals, activity\n│   │   ├── strategy-write.ts   # create/update goals, insights, dismiss signals\n│   │   ├── knowledge.ts        # documents + briefs\n│   │   ├── ingest.ts           # ingest new signals\n│   │   └── integrations.ts     # list connected sources\n│   ├── prompts/                # MCP prompt workflows\n│   ├── resources/              # MCP resources (workspace context, goals)\n│   ├── gql/                    # Generated GraphQL types (pnpm codegen)\n│   ├── graphql/                # GraphQL operation documents\n│   ├── helpers/                # OAuth provider, token minting, workspace selection, KV/Redis\n│   └── lib/                    # Squad API client, logger, telemetry\n├── railway.toml                # Railway deployment config\n└── .env.example                # Environment template\n```\n\n## 🏭 Production Deployment\n\nThis is a hosted service maintained by Squad. Users connect via OAuth — no self-hosting required.\n\n**Architecture notes (for contributors):**\n\n- Deployed on Railway with a `/health` readiness check\n- Stateless request handling, with Redis holding the per-user workspace selection and token cache, so instances scale horizontally\n- Follows the [MCP specification](https://modelcontextprotocol.io/specification) for streamable HTTP transport\n\n## 💬 Support\n\nNeed help with the Squad MCP server?\n\n- **Email:** support@meetsquad.ai\n- **Documentation:**\n  - [Squad MCP Guide](https://docs.meetsquad.ai/guides/squad-mcp) — complete setup and integration guide\n  - [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md) — real-world usage examples\n- **Issues:** [GitHub Issues](https://github.com/the-basilisk-ai/squad-mcp/issues) — bug reports and feature requests\n- **Privacy Policy:** [meetsquad.ai/privacy-policy](https://meetsquad.ai/privacy-policy)\n- **Squad Platform:** [meetsquad.ai](https://meetsquad.ai)\n\n## 🤝 Contributing\n\nContributions welcome! Pre-commit hooks run biome and vitest automatically. Please ensure:\n\n- `pnpm format` passes (biome)\n- `pnpm build` compiles without errors\n- `pnpm test` passes\n- `pnpm codegen:check` passes if you touched GraphQL operations\n- All tools include safety annotations\n\n## 📄 License\n\nMIT\n\n## 🔗 Links\n\n- [Squad MCP Documentation](https://docs.meetsquad.ai/guides/squad-mcp) — complete setup and integration guide\n- [Squad Platform](https://meetsquad.ai)\n- [MCP Specification](https://modelcontextprotocol.io)\n- [Issue Tracker](https://github.com/the-basilisk-ai/squad-mcp/issues)\n\n## GraphQL codegen\n\nBackend access is typed via GraphQL Code Generator. `schema.graphql` is a\ncommitted snapshot of the Squad platform API schema; `src/gql/` is generated\nfrom it plus the operation documents in `src/graphql/`.\n\n- Refresh the snapshot: copy `packages/graphql/src/schema/generated.graphql`\n  from the API repo over `schema.graphql` (or set `SQUAD_GRAPHQL_URL` to\n  introspect a live endpoint), then run `pnpm codegen`.\n- CI runs `pnpm codegen:check` and fails when `src/gql/` is stale.\n",
  "bytes": 14902,
  "sha": "d94327304877f7f3893ca567abed1e7e3e9ec1671a3fd64b0048afa1e4539138",
  "repo_slug": "the-basilisk-ai/squad-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_meetsquad_squad_9bbb9985/readme"
}