Sage 7 documentation

Last updated October 16, 2026

This is the complete reference for connecting coding agents to Sage 7. Use the read-only MCP server to give an approved agent project context without granting it permission to change Sage 7 data.

Overview

Sage 7 exposes an MCP server at https://sage7.dev/mcp. It lets AI assistants read your blueprints, next tasks, feature specifications, and audit evidence, and, when you allow it, report open questions and decisions to your Agent inbox (report_question, report_decision, get_answers). It cannot change the spec or run AI generation; only your answers do.

Available tools (15)

  • list_projects — Call this first in a new session, or whenever the project ID is unknown. Lists your Sage 7 blueprint projects and their IDs; audit-only projects are excluded. Read-only.
  • get_next_task — Call this once, when the owner asks you to start the next feature. Returns the highest-priority unbuilt feature the owner allows (with approval on, only one they approved) with its acceptance criteria and linked audit evidence. Build that one feature, then stop; never call it again on your own. It does not mark anything built.
  • get_feature_spec — Call this after get_next_task and before proposing a plan. Returns one feature's full specification, linked audit evidence and linked_launch_gates (pre-launch sign-offs such as legal or regulatory approvals that still block its release). Plan one feature at a time, then commit it to the develop branch with its feature ID.
  • list_features — Call this to find feature codes: returns every feature's code, name, status, plan state and stage, optionally filtered by words. Read-only; it never changes what get_next_task serves.
  • get_context_markdown — Call this when the agent needs the project-wide context.md, including AGENTS.md context. Returns the latest remaining compiled version as a tool result, not an MCP resource.
  • get_context_package — Call this when the agent needs structured context with features and design tokens, for example before UI work. Returns the serving context version, its staleness and the project's features.
  • get_context_status — Call this before refreshing context, passing the last version you read. Returns the version currently served and changes after it, so a stale context or a fallback to an earlier version is visible.
  • report_question — Call this when the spec doesn't answer something you need to build. Sends the question to the owner's inbox; blocking=true pauses that feature in the plan until it is answered: then don't decide it yourself or report it built, wait for get_answers. Always fill plain_language (no jargon, with your recommendation): most owners aren't engineers. Never changes the spec.
  • propose_feature — Call this when the feature you're asked to build needs a capability that isn't in the map at all (no feature code), for example in-app chat. Proposes it as a new feature for the owner to approve; approval gives it a feature code and makes the blocked feature wait for it. Then stop: don't build either until get_next_task returns it. Never changes the spec on its own.
  • report_decision — Call this after you make a decision the spec didn't cover (for example when you write an ADR). The owner confirms or overrules it; check get_answers before building further on it. Never changes the spec.
  • report_progress — Call this when you finish a feature, or when get_next_task returns something you already built. Records which features you believe are built, with commits and files, in the owner's inbox. The feature shows as awaiting audit; only an audit marks it built. After reporting, stop and wait for the owner. Never changes the spec.
  • report_usage — Call this when you finish a feature or a session, if your client tells you its token usage. Records the model and token counts (and cost, if your client gives one) against the feature, so the owner sees what each feature cost in AI tokens. Repeat calls with the same client_key replace the earlier figure. Never changes the spec.
  • list_launch_gates — Call this when get_feature_spec shows linked_launch_gates or context.md lists critical pre-launch gates. Returns the project's release gates (legal, regulatory, security, policy and infrastructure sign-offs) with status, owner, severity and linked feature codes. An unresolved hard blocker stops develop being promoted to main. Read-only.
  • record_gate_status — Call this when you have evidence toward a release gate, for example the integration a sign-off depends on is built and documented. Moves the gate to in_review with your evidence notes for the owner. Agents can't set satisfied or waived_with_reason: only the owner can, so the gate keeps blocking the release until they do. Never paste secrets or contract text.
  • get_answers — Call this at the start of a session and before building on a reported question or decision. Returns the owner's answers since your last call and what is still waiting. Read-only.

context.md is returned by get_context_markdown; it is not exposed as an MCP resource, so an empty resource list is expected. Context is versioned: a snapshot is rebuilt a few minutes after source changes stop, an unchanged rebuild creates no new version, and deleting a version falls back to the previous remaining one. If a tool is missing from your MCP client, confirm it is connected to the latest Sage 7 deployment, then refresh or reconnect the server.

How agents use Sage 7

Sage 7 is project context, not a code writer. The tools never edit code, dispatch builds or mark a feature built; only a valid audit can do that. Agents can report questions, decisions and progress to the owner's inbox; only the owner's answer or an audit changes anything.

  1. Read AGENTS.md and the blueprint/ documents in the repository first. They survive when MCP is not connected.
  2. Call list_projects when you need the project ID. When the owner asks you to start work, call get_next_task once for the feature to build.
  3. Call get_feature_spec for that feature, and get_context_markdown or get_context_package when you need the full context.
  4. Ask the user to approve a plan before writing code. Use get_context_status with the last version you read before refreshing.
  5. Build in stage order, like a building: Foundation, then Structure (shared engines, data and services), then Rooms (features people use), then Finishes. Only build the task get_next_task returns; work built ahead of its stage or prerequisites is held and doesn't count. If a feature needs something that isn't built, say so with report_question naming the feature code; if it isn't in the map at all, propose it with propose_feature.
  6. Work only on the develop integration branch. Never create, switch to or push feature branches to GitHub. Every commit lands on develop with its feature ID in the message, for example feat(F-108): implement ticket generation and schema, then push develop.
  7. When a feature is committed and pushed to develop, call report_progress with its feature ID and commits (add usage if your client reports token counts, or call report_usage). It shows as awaiting audit; audit evidence decides what is built, commits are only build evidence. Then stop and wait for the owner and the Sage 7 push audit on develop: don't pull or start another feature until they say so. Sage promotes develop to main only after that audit passes.
  8. When the spec doesn't answer something, call report_question (blocking=true if you can't continue) with plain_language the owner can follow without technical knowledge; report decisions you make with report_decision. Never decide or build a feature whose blocking question you asked is still unanswered. Call get_answers at the start of each session.

Commits never mark a feature as built. A commit message that includes a feature code (for example feat(F-123): ...) records build evidence only: in progress, unverified on a branch or merged, unverified on the default branch. Only valid audit evidence can mark a feature built.

Agent setup

OAuth is the default for every supported client because Sage 7 publishes OAuth metadata at /.well-known/oauth-protected-resource. Use a project token only when a client cannot complete OAuth; the token is read from the SAGE7_TOKEN environment variable and is never written into a config file.

Claude Code

Add the remote HTTP server, then run /mcp inside Claude Code and approve the Sage 7 sign-in. Claude Code stores MCP servers in its own config; OAuth prompts on first use and `/mcp` shows the approval.

OAuth (recommended)

claude mcp add --transport http sage7 https://sage7.dev/mcp
claude mcp list
# then run /mcp inside Claude Code and approve the Sage 7 sign-in

Project token fallback — Set SAGE7_TOKEN in the shell that starts Claude Code, then add the server with a header that reads the variable. Never paste the token into the command.

export SAGE7_TOKEN="<your project token>"
claude mcp add --transport http sage7 https://sage7.dev/mcp \
  --header "Authorization: Bearer $SAGE7_TOKEN"

Cursor

Cursor completes OAuth for remote HTTP servers. No token or header is needed. Save as ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), then reload Cursor's MCP panel.

OAuth (recommended)

{
  "mcpServers": {
    "sage7": {
      "url": "https://sage7.dev/mcp"
    }
  }
}

Project token fallback — For the fallback, Cursor interpolates SAGE7_TOKEN from your environment, so the config never holds the secret.

{
  "mcpServers": {
    "sage7": {
      "url": "https://sage7.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SAGE7_TOKEN}"
      }
    }
  }
}

VS Code

VS Code handles OAuth for remote HTTP servers. Start the server, then approve the Sage 7 sign-in when VS Code prompts. Save as .vscode/mcp.json in the workspace, or run MCP: Add Server from the Command Palette for a user-level server, then start it from MCP: List Servers.

OAuth (recommended)

{
  "servers": {
    "sage7": {
      "type": "http",
      "url": "https://sage7.dev/mcp"
    }
  }
}

Project token fallback — VS Code prompts for the project token at runtime through an input variable, so mcp.json holds only the reference, never the token.

{
  "inputs": [
    {
      "id": "sage7-token",
      "type": "promptString",
      "description": "Sage 7 project token",
      "password": true
    }
  ],
  "servers": {
    "sage7": {
      "type": "http",
      "url": "https://sage7.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:sage7-token}"
      }
    }
  }
}

Antigravity

Antigravity handles OAuth automatically for remote servers that support dynamic client registration. Use serverUrl, not url. Save as ~/.gemini/config/mcp_config.json globally, or .agents/mcp_config.json in a workspace, then authenticate from Agent settings.

OAuth (recommended)

{
  "mcpServers": {
    "sage7": {
      "serverUrl": "https://sage7.dev/mcp"
    }
  }
}

Project token fallback — Antigravity documents OAuth for remote servers but not environment-variable interpolation in remote headers. Sage 7 will not put a token value into mcp_config.json, so use OAuth here or a client that supports header variables.

# Prefer OAuth in Antigravity.
# A token header would be written in plain text, which Sage 7 does not recommend.

Lovable

Add Sage 7 as a custom MCP server and keep authentication on OAuth. Lovable custom MCP servers are personal chat connectors and are not part of your published app.

OAuth (recommended)

1. Open Connectors -> + -> MCP server
2. Server name: Sage 7
3. Server URL: https://sage7.dev/mcp
4. Leave authentication on OAuth, then click Add & authorize

Project token fallback — Lovable's bearer-token field expects the token value itself; it cannot read SAGE7_TOKEN. Prefer OAuth, and keep a token out of Lovable entirely when you can.

OAuth is the default. If you must use Lovable's bearer field, paste the
project token there once; it is a credential form, not a config file.

Other

Use the remote HTTP URL; clients that publish OAuth metadata will prompt for approval on first use. Most MCP clients accept this remote-server shape. Check your client's docs for the exact file location.

OAuth (recommended)

{
  "mcpServers": {
    "sage7": {
      "url": "https://sage7.dev/mcp"
    }
  }
}

Project token fallback — Use your client's environment-variable syntax for SAGE7_TOKEN; never paste the token value into the file.

{
  "mcpServers": {
    "sage7": {
      "url": "https://sage7.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SAGE7_TOKEN}"
      }
    }
  }
}

Examples

See the full MCP examples page for prompts for starting a project, building the next task, and checking a result with an audit.

Start a new project

  • List my Sage 7 projects and summarize the blueprint for the one I should work on first.

Build the next task

  • Call get_next_task, then get_feature_spec, and propose a plan before writing code.

Check a result with an audit

  • Compare the implemented checkout feature with its Sage 7 spec and summarize gaps.

Analyze your own application with REA, then import evidence

REA can analyze a local JavaScript or Electron application and emit a JSON report. Run it only for software you own or are authorized to analyze. Pin an exact published REA version instead of using latest; the REA documentation currently includes 6.4.0 examples, so verify that release and its requirements from the official repository before use.

npx --yes rea-agents@6.4.0 analyze-javascript-application "C:\path\to\your\app" --json > application-evidence.json

Review the report locally and verify its evidence references before importing. If you need REA to register an MCP server with your coding agent, preview the exact-version setup plan first with npx --yes rea-agents@6.4.0 setup --dry-run. Review all paths and proposed configuration changes before approving setup; do not accept changes for every detected agent by default.

In the project's Audit area, choose Import evidence and provide the tool name/version, target description, findings, and evidence references in Markdown or JSON. Sage retains the submitted report as untrusted evidence and never treats its contents as instructions or sends them to an AI model. Findings start as imported, unverified; a human must confirm or reject each one in Decisions. Only confirmed findings can be drafted into the Taxonomy Map, where each proposed feature needs individual approval.

Do not import source archives, credentials, private keys, customer data, or unrelated sensitive material. The import is capped at 256 KB and stores the submitted report with the project for review.

Security and limits

Connections are read-only and scoped to approved projects. MCP requests are rate-limited per credential; the default ceiling is 60 requests per minute and the deployment can change it with MCP_RATE_LIMIT_PER_MINUTE. Project tokens expire after 30 days and can be revoked from the project's Connect Agent tab.

Troubleshooting and support

Confirm the endpoint, complete OAuth approval, verify the client is enabled, and retry its list/debug command. If the issue remains, email support@sage7.dev with the client name and error message, never a token.

How to · Terms · Privacy · Refunds · Pricing