Use Graphrun with an AI agent

Create an Agent Access Key

Each key belongs to one workspace and one approved MCP client. Give every client its own key so you can see where it is used, rotate it, or revoke it without interrupting other clients.

1. 1Open your account menu, choose Settings, and select the workspace the client should access. You can also go directly to Agent Access Keys.
2. 2Choose Create Agent Access Key and enter a name that identifies the client and device, such as Coding agent on my laptop.
3. 3Choose View diagrams only for explanation and review, Full MCP access for a trusted client that should create, edit, and run work, or Custom access for a smaller grant.
4. 4Choose an expiry. Keys that can make changes must expire within 14 days; Full MCP access starts with a seven-day expiry.
5. 5Review the access summary, create the key, and copy it immediately. Graphrun shows the complete key only once.

Connect your MCP client

Add the Graphrun Streamable HTTP server to your client. The server is the API address, not the website address, and the key must be sent as a Bearer Authorization header.

Choose your client below. Each example keeps the key in an environment variable or password prompt rather than a tracked project file.

# Load GRAPHRUN_AGENT_ACCESS_KEY from your approved secret store.
npx @modelcontextprotocol/inspector \
  --cli \
  --server-url "https://api.graphrun.app/mcp/v2" \
  --transport http \
  --header "Authorization: Bearer ${GRAPHRUN_AGENT_ACCESS_KEY}"

{
  "mcpServers": {
    "graphrun": {
      "type": "http",
      "url": "https://api.graphrun.app/mcp/v2",
      "headers": {
        "Authorization": "Bearer ${GRAPHRUN_AGENT_ACCESS_KEY}"
      }
    }
  }
}

{
  "servers": {
    "graphrun": {
      "type": "http",
      "url": "https://api.graphrun.app/mcp/v2",
      "headers": {
        "Authorization": "Bearer ${input:graphrun-agent-access-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "graphrun-agent-access-key",
      "description": "Graphrun agent access key",
      "password": true
    }
  ]
}

# Load GRAPHRUN_AGENT_ACCESS_KEY from your approved secret store.
codex mcp add graphrun \
  --url "https://api.graphrun.app/mcp/v2" \
  --bearer-token-env-var "GRAPHRUN_AGENT_ACCESS_KEY"

Verify the connection

1. 1Close and restart the MCP client after adding the key.
2. 2Ask the client to connect to Graphrun and list the diagrams it can access.
3. 3Ask it to summarize its Graphrun capabilities and any missing permissions or workspace settings.
4. 4Start with a small read request, such as “Explain the checkout diagram without making changes,” before asking it to author or run a larger slice.

Choose the smallest useful access

Custom authoring needs write access enabled, the matching actions and information types, and a diagram grant that follows the latest draft. Diagram creation also needs its separate creation switch enabled. For journey authoring and execution, choose View journeys, Create and edit journeys, the Journeys information type, and the owner-confirmed Real stored values payload policy. Add View diagrams and Diagrams and architecture to discover valid journey starts. Merely choosing Structure only cannot authorize a run.

Add the model-authoring skill

Pair your MCP connection with the author-graphrun-models skill so your coding agent follows Graphrun's discovery, authoring, and verification workflow. The Skills guide explains how skills and MCP work together, links the public repository, and includes installation steps and example prompts for your coding agent.

What you can do through MCP

Graphrun gives an MCP client a grant-scoped architecture workspace. The client can combine Graphrun with the files, tickets, or repositories it can already access. The Agent Access Key, workspace write controls, and server availability determine which Graphrun operations are usable. These prompts describe tasks for the agent, not additional built-in tools or a guarantee that every requested feature is modeled.

Run and verify journeys through MCP

Journey tools retain their existing API names. Read the current authoring context with get_scenario_authoring_context, then list or create the saved journey draft. Before running, read it with get_scenario_draft and pass its returned version_token as scenario_version_token to run_scenario_draft. Do not substitute the graph token, a reference from another key, or an ID copied from the browser address bar.

The server worker runs that exact saved journey against the current follow-latest graph. It does not persist a run artifact or add an approved run to your workspace. Review the returned status, outcome, execution coverage, and trace; a successful tool call can still contain a failed, guarded, or rejected modeled journey. Run every critical success and failure path, not just the easiest one to finish.

Responses default to a bounded summary. Ask for full detail and paginate when you need more evidence. See MCP event pages and coverage for limits, filtering, and reference handling. A diagram checkpoint saves selected journey inputs, not this transient run evidence.

Map an existing codebase without sending its source

Open a diagram's Implementation tab when the system already has a repository. Graphrun can give a connected coding agent stable architecture, contract, data-resource, and mapping targets without receiving repository files or credentials.

1. 1Choose Create mapper key. The preset is scoped to this diagram, follows its latest revision, exposes structure only, and expires after seven days. It permits implementation mapping writes, not graph or contract edits or journey runs.
2. 2Configure the key in the MCP client, then return to the Implementation tab and choose Copy MCP task.
3. 3Run the task from the local repository. The agent lists diagrams, reads the manifest's implementation-context link, and compares stable targets with local files, symbols, manifests, CODEOWNERS, and Git refs.
4. 4Keep evidence metadata-only. Repository paths, symbol names, manifest kinds, CODEOWNERS matches, and Git refs are supported; source snippets, file or manifest bodies, credentials, and arbitrary structured payloads are rejected.
5. 5If apply_implementation_bindings is advertised, the agent can create or replace up to 100 mappings in one atomic batch. Successful mappings become active immediately: there is no proposal or approval queue. Ask for a candidate list first if you want to review before any write. If the tool is absent, return candidates without changing Graphrun.
6. 6Reread the mapping context and bindings after a committed batch. Corrections use the current binding reference and version, not a duplicate create. You can edit or remove active mappings in the Implementation tab; uncertain targets should remain unmapped.

Give the agent a safe working loop

1. 1Discover: list available diagrams, select the target, and read the current model before planning changes.
2. 2Plan: ask for a bounded change slice that includes graph behavior, contracts or resources when needed, and at least one journey that can prove the route.
3. 3Author: let the agent use Graphrun's current component catalog and operation guidance instead of guessing component ports or write shapes.
4. 4Verify: validate the graph, check contract gaps, and run the saved critical journey. A connection alone is not executable behavior; handlers must own the response, failure, or message action.
5. 5Report: summarize evidence, assumptions, unresolved warnings, and exactly what changed. Create a checkpoint only when you need a stable review point.

What MCP deliberately cannot do

MCP can edit drafts, run transient journeys when enabled, validate work, and create checkpoints. It cannot approve contracts, publish work, create approved runs, create share links, or create exports. Authorized readers can retrieve existing approved artifacts, including contract downloads. Contract approval remains a signed-in web action; run publication and share creation are currently disabled in the alpha editor.

Troubleshooting

Continue learning

Read Journeys to learn how Graphrun explains successful and failed system paths, or Contracts and data to model APIs, messages, schemas, and logical resources.