MCP server

The StackShip MCP server lets an AI agent, such as Claude, Cursor, or VS Code, look up workspaces, follow runs, review plans, and make changes you allow. The agent acts as you, in one organization, and never exceeds your role.

Server URL

https://mcp.stackship.run/mcp

The server uses the Streamable HTTP transport and OAuth, so there’s no token to create or paste.

Connect your agent

Add the URL above as a remote MCP server in your client:

Claude Code

claude mcp add --transport http stackship https://mcp.stackship.run/mcp

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{
  "mcpServers": {
    "stackship": { "url": "https://mcp.stackship.run/mcp" }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "stackship": { "type": "http", "url": "https://mcp.stackship.run/mcp" }
  }
}

Any client that supports remote MCP servers with OAuth works. If it asks for a server type, choose HTTP or Streamable HTTP.

Approve the connection

The first time your agent connects, your browser opens StackShip:

1. Sign in, if you aren’t already.
2. Choose the organization the agent should work in.
3. Review the consent screen and select Authorize.

To work in a different organization later, disconnect and authorize again.

Scopes: read or read and write

The client must request mcp:write explicitly. Even then, every action needs the matching permission in your role. For example, a member can start runs but can’t approve them.

What the agent can do

Read (with mcp:tools):

• List projects, workspaces, and their GitHub source settings.
• Follow runs across the organization or in one workspace (stackship_list_runs, filterable by status, kind, and workspace_id; kind: drift_check lists drift checks).
• Read a workspace’s drift detection schedule (stackship_get_workspace_schedule).
• Read a run’s review, plan change summary, policy results, and logs.
• List state versions, workspace variables (sensitive values are never shown), and cross-workspace state access.
• Read the audit log, policy sets and their attachments at every scope (stackship_list_policy_set_attachments), the private module registry, credential profile metadata and trust templates, and available OpenTofu versions.

Change (with mcp:write):

• Create projects and workspaces, update workspace settings, set a workspace’s GitHub source, and turn on or change its drift detection schedule (stackship_update_workspace_schedule). Turning drift detection off is dashboard-only.
• Start, approve, reject, and cancel runs, and force cancel an applying run whose cancel is already pending (stackship_force_cancel_run). Force cancel stops OpenTofu immediately, and the run then needs recovery.
• Create and update workspace variables. Sensitive values stay write-only.
• Create policy sets, attach policy versions, and record a justified soft policy override.
• Add registry modules, sync tags, change a module’s source, and deprecate or restore versions.

Tool names start with stackship_, for example stackship_get_run_review. stackship_status reports the signed-in user, organization, and scopes.

Not available to agents

These actions are dashboard-only:

• deleting anything, including variables, modules, policy attachments, and drift detection schedules;
• creating workspace tokens;
• creating, changing, verifying, or revoking credential profiles;
• granting cross-workspace state access;
• downloading raw state or sensitive artifacts, and apply recovery;
• uploading policy source; and
• installing the GitHub App.

Approvals stay in your control

An agent can only approve the exact plan it reviewed. It must read the run review first; if the plan or policy results change before it approves, the approval is rejected. Blocked policy checks can’t be approved. See Run approvals.

Audit trail

Agent changes appear in the audit log under your name, marked as MCP actions with the agent’s client ID.

Disconnect an agent

Remove the server in your MCP client. Without offline_access, access ends within an hour. Removing someone from the organization stops their agents right away. StackShip doesn’t yet have a page listing connected agents.

Troubleshooting

Next steps

• Signing in and account security
• REST API
• Run approvals
• Audit log