GitHub Copilot
Use SpecsGraph from GitHub Copilot agent mode in VS Code: add the MCP server to .vscode/mcp.json, sign in when VS Code asks and call its tools.
Before you start
- Visual Studio Code with GitHub Copilot signed in.
- A SpecsGraph account in an organisation, with the Editor role or above if the agent should stage changes. A Viewer's agent reads, comments and asks questions.
- The SpecsGraph MCP URL,
https://mcp.specsgraph.io/mcp; see The MCP URL. - If you get Copilot through an organization, an admin may need to allow MCP servers in the organization's Copilot policies first.
Add the server to .vscode/mcp.json
Create .vscode/mcp.json in your repository. It holds only the URL, so you can commit it and every teammate signs in with their own account. For a server that follows you across all your projects, run MCP: Open User Configuration from the Command Palette and add the same entry there.
{
"servers": {
"specsgraph": {
"type": "http",
"url": "https://mcp.specsgraph.io/mcp"
}
}
}With a personal access token
If sign-in is not available to you, let VS Code prompt for a personal access token instead of reading it from the file. "password": true hides it while you type, and VS Code keeps it in its secure storage.
{
"inputs": [
{
"type": "promptString",
"id": "specsgraph-token",
"description": "SpecsGraph personal access token",
"password": true
}
],
"servers": {
"specsgraph": {
"type": "http",
"url": "https://mcp.specsgraph.io/mcp",
"headers": {
"Authorization": "Bearer ${input:specsgraph-token}"
}
}
}
}Note
VS Code's own documentation is the authority on the mcp.json format and on Copilot's agent mode. The examples here reflect VS Code at the time of writing.
Start the server and check its tools
Start the server
Open
.vscode/mcp.jsonand select Start above thespecsgraphentry, or runMCP: List Serversand start it there.Sign in
VS Code asks to sign in and opens SpecsGraph in your browser. Pick the organisation, access and projects and choose Allow. With a token, VS Code asks for it once instead.
Confirm it is running
The entry should show as running with 52 tools, starting with
project_list. If it fails,MCP: List Serverslets you open the server's output log, which shows the HTTP status of the failed request (401is the sign-in or token,404the URL).
Use agent mode
MCP tools are available when Copilot Chat runs in agent mode:
- Open the Chat view and switch the mode picker to Agent.
- Select the tools button in the chat input and check that the
specsgraphtools are enabled. Turn off any you do not want the agent to use. - Ask your question. Copilot calls SpecsGraph tools when the prompt needs them, and you can type
#in the chat input to point it at a specific tool such as#spec_get. - Confirm each tool call when VS Code asks. Read the arguments of
spec_applycalls before you continue, since they stage revisions under your name into a proposal.
Add repository instructions
Copilot in VS Code reads .github/copilot-instructions.md for every chat request in the repository. A few lines there make it check SpecsGraph first.
The spec for this repository lives in SpecsGraph (MCP server `specsgraph`). Main is the spec
that shipped; a workstream holds the spec in flight until one of its tasks publishes. Before changing
behaviour, read the relevant documents there: `project_list`, then `spec_get` with a `kind/Name`
selector (`scope: workstream:WS-n` while in flight, `scope: main` for what shipped), and
`workstream_listChanges` for what a workstream already changes. Use its glossary terms in code.
When behaviour changes, stage the spec change with `spec_apply` into the workstream (a person
reviews the proposal) and cite display ids such as WS-3 and T-4 in commit messages.Example prompts
Copilot in other editors
Copilot also supports MCP in other editors, and each uses its own configuration file. The values are always the same: https://mcp.specsgraph.io/mcp, with sign-in or the header Authorization: Bearer <token>. Check that editor's Copilot documentation for where they go, and see Other MCP clients for the general pattern.
Next steps
- Working well with agents: prompts and review habits for agent proposals.
- MCP tool reference: what each tool reads or stages.
- Agent skills: guided modeling workflows, installed with
npx skills add SpecsGraph/specsgraph-skills.