Skip to content

GitHub Copilot

Use SpecsGraph from GitHub Copilot agent mode in VS Code: add the MCP server to .vscode/mcp.json, enter your token once and call its tools.

Before you start

  • Visual Studio Code with GitHub Copilot signed in.
  • Your SpecsGraph server's MCP URL. The examples use https://specsgraph.example.com/mcp; see Find your server's MCP URL.
  • A personal access token. VS Code asks for it once and stores it, so you do not need SPECSGRAPH_TOKEN set for this client.
  • 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. The inputs entry makes VS Code prompt for the token instead of reading it from the file, and "password": true hides it while you type.

.vscode/mcp.jsonJSON
{
  "inputs": [
    {
      "type": "promptString",
      "id": "specsgraph-token",
      "description": "SpecsGraph personal access token",
      "password": true
    }
  ],
  "servers": {
    "specsgraph": {
      "type": "http",
      "url": "https://specsgraph.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:specsgraph-token}"
      }
    }
  }
}

The file contains no secret, so you can commit it and every teammate gets the server with their own token. For a server that follows you across all your projects, run MCP: Open User Configuration from the Command Palette and add the same entries there.

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 from the Command Palette and start it there.

  2. Enter your token

    VS Code prompts for the token the first time the server starts. Paste the value that begins with sgp_. VS Code keeps it in its secure storage for later sessions.

  3. Confirm it is running

    The entry should show as running with the number of tools it offers. If it fails, MCP: List Servers lets you open the server's output log, which shows the HTTP status of the failed request.

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.
  4. Confirm each tool call when VS Code asks. Read the arguments of write-tool calls before you continue, since they open proposals under your name.

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
Requirements, domain terms and design decisions for this repository live in
SpecsGraph (MCP server `specsgraph`). Before changing behavior, read the
relevant context and requirements there. Use its glossary terms in code.
When behavior changes, propose the spec change in SpecsGraph and cite
requirement IDs such as ORD-12 in commit messages.

Example prompts

GoalPrompt
Implement against a requirement"Get ORD-12 from SpecsGraph and implement the reservation step in the checkout service so every scenario passes."
Explain a context"Use SpecsGraph to explain how Billing and Orders relate and which requirements cross that boundary."
Draft a spec change"Propose a change to ORD-13 in SpecsGraph: extend the idle timeout for carts with more than 20 line items. Add a scenario for it."
Track the work"Mark the task 'Specify the email sent when a reservation lapses' in WS-3 as in progress."

Copilot in other editors

Copilot also supports MCP in other editors, and each uses its own configuration file. The values are always the same: your server's MCP URL and 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