Skip to main content

4. Connect external tools

Your project works on its own. It becomes a lot more useful once the same project state is reachable from Copilot CLI, upstream Squad, and (when you are ready) GitHub. This tutorial wires the outer surfaces around the loop you ran in Tutorial 3.

How these three pieces fit together​

Squadboard is the multi-agent inner loop — capture, shape, route, run, review — that happens before work reaches GitHub.

  • Upstream Squad owns the on-disk operating convention: agents, charters, decisions, ceremonies all live in .squad/. Squadboard reads and writes that folder; it does not replace it.
  • Copilot CLI uses MCP to call your project's tools (capture, create_issue, run_agent, get_run_status) instead of editing the database directly.
  • GitHub is the outer loop — issues, pull requests, checks, review signals — that reflects work after the inner loop has done its job.
Shared storage status

By default, Squadboard stores Squad state in PostgreSQL (the same database that stores product state). Existing .squad/ files are imported once into an empty DB-backed project. Filesystem .squad/ mode is still available as an explicit fallback.

Quick setup:

pnpm run dev

This uses Squadboard's embedded PostgreSQL database (PGlite) by default and imports any existing .squad/ files on startup (one-time). Four approaches:

  1. Embedded PostgreSQL (zero-config) — Run pnpm run dev, pnpm run dev:postgresql, or squadboard init; PGlite handles everything.
  2. External PostgreSQL (multi-machine) — Override with DATABASE_URL pointing to a shared instance; multiple compatible processes can share state directly.
  3. MCP bridge (portable) — Squadboard exposes tools; Copilot CLI calls them instead of direct DB access (works with stock Copilot CLI).
  4. Filesystem fallback — Run pnpm run dev:fs or squadboard init --squad-storage fs when .squad/ files should remain the live state store.

See Storage provider — Configuration recipes for concrete examples and when to use each.

1. Add an MCP server for the bridge​

Open MCP Servers. This page lists every external tool bridge your project exposes.

Click New MCP server and fill in a recognizable name plus the endpoint your client will use:

  • For local Copilot CLI, use the stdio CLI command from MCP integration instead of an HTTP URL.
  • For a hosted MCP gateway, paste the HTTP endpoint and any required credential ID.

Save. The bridge appears in the list and is immediately callable by clients pointed at it.

What Copilot CLI can now do with your project​

With the MCP bridge in place, a developer in Copilot CLI can:

  • Drop a freeform note into your project's Inbox with capture.
  • Create a structured card with create_issue (it lands in Backlog so a human can still shape it).
  • Trigger a run with run_agent and check progress with get_run_status.

The result of every call shows up on your project board with the same audit trail as if you had clicked through the UI. Copilot CLI does not need (and should not have) direct database access.

2. Connect GitHub as the outer loop​

When the team is ready for issues, pull requests, checks, and review signals to flow back into your project, connect GitHub. Open Settings.

Switch to the GitHub tab and connect the repository, install the app, and configure label and webhook routing.

Once connected:

  • GitHub issues with matching labels become project cards.
  • Project runs that produce PRs link back from the card.
  • Check and review state flows back into the board so ceremonies can act on it.

For the policy and webhook details, see GitHub integration.

3. Save your project as a template (portability)​

If your project turned into a workflow loop you want to reuse — same team shape, same ceremonies, same board structure — save it as a template before you tear it down or move on.

Open Settings → Portability.

Click Save as template. The export includes:

  • Board column structure.
  • Agents, roles, and charters.
  • Ceremonies and their workflows.
  • Skills and tool instructions.
  • MCP recipes (with credential placeholders, never the secrets).

Anyone starting a new project can pick this template in step 1 of Tutorial 1 and skip straight to capturing work.

What you have now​

  • An MCP server entry that lets Copilot CLI work with your project without direct DB access.
  • GitHub connected (optional) so the outer loop reinforces the inner loop.
  • Your project saved as a reusable template.

Where to go next​

Last updated on