> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useshipd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> The operational MCP tool surface, access boundaries, version checks, and seven-day mutation retry contract.

## Overview

The remote MCP endpoint is `https://mcp.useshipd.com/mcp`. Each connection delegates one user's current permissions within one organization and optionally selected projects. [Connect an agent](/operations/connect-an-agent) for client setup.

## Available tools

| Resource | Tools |
| - | - |
| Projects | `project_list`, `project_create`, `project_update` |
| Environments | `environment_list`, `environment_create`, `environment_update` |
| Flags | `flag_list`, `flag_get`, `flag_create`, `flag_update`, `flag_listEnvironmentStates`, `flag_updateEnvironment`, `flag_toggleEnvironment` |
| Audiences | `segment_list`, `segment_get`, `segment_create`, `segment_update`, `segment_listEnvironmentStates`, `segment_updateEnvironment` |
| Evaluated identities | `evaluatedEntity_list`, `evaluatedEntity_get` |
| Evaluation diagnostics | `evaluationFact_list`, `evaluationFact_byRule`, `evaluationFact_projectSummary` |
| Change review | `mcp_history`, `mcp_approvalStatus` |

Read-only connections discover only read tools. Every call is independently authorized; a tool appearing in discovery does not mean your role permits its use.

Project creation requires an all-projects connection. Environment creation defaults to a development environment. Admins and owners with write connections can pass `isProduction: true` to `environment_create`, or `isProduction: true | false` to `environment_update`. Promoting an existing environment removes production status from the project's previous production environment. Production status changes require existing permissions. Approval policies can block production status updates and govern production flag changes; environment creation does not check approval policies.

Deletion and archive tools, billing, identity/security administration, credential issuance, webhook management, and snapshot recovery are outside this surface.

## Mutation inputs

```ts theme={null}
// Additional inputs required for MCP mutations.
type Mutation = {
  idempotencyKey: string; // 1–256 printable ASCII characters, without spaces
};

type Update = Mutation & {
  expectedVersion: number; // version returned by the latest resource read
};
```

Use a unique idempotency key for each logical mutation. Read before updating. Use the flag definition version for `flag_update`; use the environment-state version for flag or audience environment updates. Project and environment list responses include metadata versions, distinct from snapshot versions.

**Errors.** A stale version returns a conflict. Read the resource again, revise the proposed change, and use a new key for that new operation. There is no force-overwrite tool.

## Retries

Mutation outcomes are retained for seven days, scoped to the authorization, organization, and operation. Refreshing an access token does not change this scope.

Repeat the same key and unchanged input to retrieve a completed outcome. Changed input under the same key returns a conflict. Concurrent or uncertain outcomes remain in progress so a retry cannot apply the mutation twice. An approval submission retry returns the original request, rather than creating another.

If an outcome stays in progress after a service failure, reconcile the resource and change history before taking another action. After seven days, reconcile state before retrying; the replay record may have expired.

## Pending approval

A protected flag change returns `outcome: "pending_approval"`, the approval request, and a dashboard review link. It has not been applied. `mcp_approvalStatus` reports the status of your submitted request, subject to current project access. MCP cannot approve, reject, or relax policies.

## Eligibility and history

Active, trialing, and past-due Pro, Teams, and Enterprise organizations qualify. Downgrades remove access when the subscription snapshot is refreshed. Entitlements normally refresh after ten minutes; during a billing outage, a previously verified snapshot is accepted for at most one hour. Unknown eligibility denies access.

`mcp_history` returns operational events within your current project access and the organization’s effective audit retention window. It filters operational actions before pagination:

```ts theme={null}
type HistoryPage = {
  events: AuditEvent[];
  nextCursor: number | null;
};
```

Pass `nextCursor` as `cursor` on the next call. A null cursor means there are no more events. Changes identify the authorizing user and MCP client/connection. Credential values are redacted.

## OAuth scopes

Clients request `shipd:read` for read-only access or `shipd:read shipd:write` for write access. A write-only scope request is rejected. Browser authorization uses S256 PKCE; clients must bind token requests to the MCP resource `https://mcp.useshipd.com/mcp`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.