Setup

Specboard exposes your planning board to AI assistants over MCP at https://specboard.io/mcp. The same server works everywhere Claude runs; how you connect depends on the surface.

Claude Code

In a terminal, the desktop app, or an IDE extension, install the Specboard plugin from inside a session:

/plugin marketplace add https://specboard.io/claude
/plugin install specboard@specboard

This registers the MCP server and installs two skills: /specboard:whats-next discovers work, scopes it, and keeps board status accurate; /specboard:complete verifies finished work, finalizes the PR, and closes the item out. On first connect, an OAuth flow opens in your browser to authenticate.

Bind a repo to a project (optional)

To make every session in a repo target one Specboard project automatically, commit a project-scoped .mcp.json at the repo root carrying that project's address, owner/project, the same pair you see in its Specboard URL (/projects/<owner>/<project>/planning):

{
	"mcpServers": {
		"specboard": {
			"type": "http",
			"url": "https://specboard.io/mcp",
			"headers": { "X-Specboard-Project": "<owner>/<project>" }
		}
	}
}

A bare <project> also works, but it means each caller's own project of that slug, so anyone else who clones the repo gets "project not found". Use the full form in any repo with collaborators.

This entry overrides the plugin's server in that repo, so expect a one-time sign-in and trust prompt the first time it connects. The address is a shared reference, not a credential; each user still authenticates individually, and access is checked per user against that project.

Claude app (claude.ai and desktop)

Add Specboard as a connector so any chat can read and update your board: in Claude's settings, open Connectors, choose Add custom connector, and enter https://specboard.io/mcp. You authenticate once and the connector is available across web, desktop, and mobile.

A connector is account-level, so it does not carry a repo's project binding; Claude will see all of your projects and ask which one to use.

Cloud VMs (Claude Code on the web, CI sandboxes)

Cloud environments rebuild their container for every session and start behind a restrictive egress proxy, so a plain plugin install neither succeeds nor survives. Three one-time settings fix this.

1. Allow the network. Add specboard.io to the environment's network allowlist. The default policy blocks it, which prevents the plugin catalog from being fetched at all.

2. Reinstall on startup. Plugins live in a directory that is discarded with the container, so add this to the environment's startup script:

claude plugin marketplace add https://specboard.io/claude
claude plugin install specboard@specboard --scope user

Both commands are idempotent and safe to run every session. --scope user installs the plugin for every repo in the VM.

3. Authenticate through a connector. A headless session cannot complete the MCP OAuth browser redirect, so add Specboard as a claude.ai connector (previous section) instead. It authenticates once at the account level and works in cloud sessions. Never put a token in a startup script.

Using it

From any connected session, ask "what's next?" or run /specboard:whats-next. Claude queries your projects, checks local git state, and recommends what to pick up; as work progresses it keeps the board current: scoping, task breakdown, status, branches, and PRs.

Back to Specboard