Skip to content

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.

.vscode/mcp.jsonJSON
{
  "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.

.vscode/mcp.json with a tokenJSON
{
  "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

  1. Start the server

    Open .vscode/mcp.json and select Start above the specsgraph entry, or run MCP: List Servers and start it there.

  2. 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.

  3. Confirm it is running

    The entry should show as running with 52 tools, starting with project_list. If it fails, MCP: List Servers lets you open the server's output log, which shows the HTTP status of the failed request (401 is the sign-in or token, 404 the URL).

Use agent mode

MCP tools are available when Copilot Chat runs in agent mode:

  1. Open the Chat view and switch the mode picker to Agent.
  2. Select the tools button in the chat input and check that the specsgraph tools are enabled. Turn off any you do not want the agent to use.
  3. 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.
  4. Confirm each tool call when VS Code asks. Read the arguments of spec_apply calls 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.

.github/copilot-instructions.mdMarkdown
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

GoalPrompt
Implement against a use case"Get the Reserve stock use case from SpecsGraph and implement the reservation step in the checkout service so every scenario of the Checkout feature passes."
Explain a context"Use SpecsGraph to explain how Billing and Ordering relate and which use cases cross that boundary."
Stage a spec change"Stage a change to the Reserve stock use case in WS-3: extend the idle timeout for carts with more than 20 line items. Add a scenario for it."
Track the work"List the tasks of WS-3 and start the one named 'Specify the email sent when a reservation lapses'."

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