Skip to content

Quickstart

Sign in to SpecsGraph, create an organisation and a project, connect an agent and publish a first change: from an empty project to a commit in your repository.

SpecsGraph is hosted, so there is nothing to install on your side. This guide uses a small online store as the example (bounded contexts such as Orders, Billing and Catalog); swap in your own system as you go.

Before you start

  • A GitHub or GitLab repository for the spec, and rights to connect it (a GitHub App install or a GitLab access token).
  • Claude Code, Codex, Cursor or another MCP client in that repository; see Connect an agent.
  • A rough idea of the main parts of your system. You do not need a written spec.

Set up and publish your first change

  1. Sign in

    Open the SpecsGraph web app (opens in a new tab) and sign in.

  2. Create an organisation and a project

    Create an organisation (Northwind), then a project with a short key (shop). The key appears in URLs and branch names. Organisations and projects explains when to split a system into several projects.

  3. Connect the repository

    In Settings, then Integrations connect GitHub (install the SpecsGraph GitHub App on the repository) or GitLab. Then in the project's Settings, then Git pick the repository, the base branch, the spec folder (default .specsgraph) and the publish mode: pull request or direct commit. A project without a repository still publishes, to Main only ("Published without git"). Connect GitHub or GitLab explains each permission.

  4. Open a workstream

    Choose Start a workstream and name it after the change, for example Reserve stock at checkout. It becomes your current workstream. You can also give it the story's tracker key (KAN-43) and open its first task at once.

  5. Connect your agent

    From your repository, register the SpecsGraph MCP URL, https://mcp.specsgraph.io/mcp. In Claude Code, run /mcp, choose specsgraph and Authenticate. Your browser opens SpecsGraph: pick Read and write access, because the agent will stage changes, limit it to the shop project and choose Allow. The Connect an agent panel in Settings, then Access tokens shows the command or file for other clients. A client that cannot sign in uses an access token instead: create one with Read and write access, limited to the project. It starts with sgp_ and is shown once; see Access tokens and agent sign-in.

    Shell
    claude mcp add --transport http specsgraph https://mcp.specsgraph.io/mcp
    
    # or, with an access token
    export SPECSGRAPH_TOKEN="sgp_paste-your-token-here"
    claude mcp add --transport http specsgraph https://mcp.specsgraph.io/mcp \
      --header "Authorization: Bearer $SPECSGRAPH_TOKEN"
  6. Ask the agent for a change

    Ask your agent to read the Orders context and add a use case, as in the prompt below. The agent reads with spec_get and stages with spec_apply. Its edits wait in the workstream's proposal.

    PromptText
    Use the specsgraph MCP server. Read workstream WS-1 of project shop,
    then add a command use case Reserve stock in the Orders context, with
    an outcome for a line item that cannot be reserved.
  7. Accept what the agent staged

    Open Proposals in the sidebar. Read each staged revision against the workstream and choose Accept (or Accept all). Comment on anything that is off; the agent reads the thread and stages again. Accepted revisions are changes of the workstream; Main does not move yet. Proposals, plans and review covers the details.

  8. Scope a task and mark it Ready

    Open Changes, select the changes that ship together and choose Add to task, or open Tasks, then New task. Mark the task Ready: that records its agreement. When the agent staged a plan, accepting the plan as a group makes it a task.

  9. Publish

    Choose Publish on the task. In pull request mode SpecsGraph pushes the branch spec/shop/t-1-<name> and opens a pull request with the YAML files; merge it, then choose Check now (or wait for the next check, every five minutes). Main advances and the task is Done by itself.

If the agent cannot connect

  • The client reports 401. The agent's sign-in was revoked in Settings, then Access tokens, then Signed-in agents or expired, or its token is wrong, revoked or expired, or the header is missing. Authenticate again from /mcp, or create a new token and check the Authorization: Bearer header.
  • The client reports 403 on a write. The sign-in or token is read only, or does not include the project.
  • The connection times out or returns 404. Check that the URL is exactly https://mcp.specsgraph.io/mcp, path included, and that no firewall or proxy on your network blocks it.
  • The client lists no tools. Restart the client after adding the server.

Troubleshooting covers more cases, from sign-in to publishing.

Next steps