Start · MCP server

Let your agent manage flags over MCP

The Darkship MCP server lets an AI agent (Claude Code, Cursor, Claude Desktop and any MCP client) list projects, change flags, edit targeting and read the audit log. It is a thin layer over the public REST API: the agent uses your API token, so it can never do more than that token allows, and every change is audited.

Updated Oct 28, 20263 min read Edit this page on GitHub (opens in a new tab)

Connect#

The server is remote and needs no installation. Create an API token in the console (the API tokens page) with the scopes you want the agent to have, then add the server to your client.

JSONMCP client configuration

{
  "mcpServers": {
    "darkship": {
      "url": "https://mcp.darkship.tech/mcp",
      "headers": { "Authorization": "Bearer ds_pat_..." }
    }
  }
}

With Claude Code, the same thing from the terminal:

ShellClaude Code

claude mcp add --transport http darkship https://mcp.darkship.tech/mcp \
  --header "Authorization: Bearer ds_pat_..."

The transport is MCP Streamable HTTP, stateless: there are no sessions, and the token travels on every request. A missing or malformed token gets 401 before anything else happens. Keep the token in your client's secret store, never in a repository.

Choose the token's scopes#

The server asks the API what your token can do and lists only the tools the token is allowed to use. If a tool is called without the scope, the error names the missing scope. There is no separate read-only switch: a token with read scopes only is a read-only agent. A token can also be limited to specific projects and environments and can expire (up to 365 days).

Agent role	Scopes
Read-only (inspect flags, audit, usage)	`project:read` `environment:read` `flag:read` `audit:read` `usage:read` `sdk_key:read`
Flag operator (toggle, rollout, targeting)	read scopes above plus `flag:write`
Flag author (also creates flags and segments)	flag operator plus `segment:manage`
Project setup (creates projects and environments)	flag author plus `project:manage` `environment:manage`

Prefer the smallest set, limit the token to the projects and environments the agent needs, and set an expiry. For day-to-day work, avoid giving an agent write access to production environments at all.

Tools#

Area	Tools
Account	`whoami`
Projects and environments	`list_projects` `get_project` `create_project` `list_environments` `create_environment`
Flags	`list_flags` `get_flag` `create_flag` `update_flag` `flag_history`
Flag configuration per environment	`get_flag_config` `toggle_flag` `set_rollout` `add_target_rule` `remove_target_rule` `set_targets` `evaluate_preview`
Segments	`list_segments` `get_segment` `create_segment` `update_segment`
Observability	`list_sdk_keys` (metadata only, never a secret) `audit_log` `usage`

Projects and environments can be given by key or by id. Not available on purpose: billing, members and invitations, organization changes, webhooks, API-token management, creating, rotating or revoking SDK keys, and every irreversible action (deleting or archiving a flag, deleting a segment, project or environment, restoring from history). Do those in the console.

Production safety#

Production changes need confirm: true. An environment counts as production when its key is prod or production, or when it requires confirmation. Without confirm the tool changes nothing and returns a before and after diff, so the agent (and you) can review it. Repeating the call with confirm: true applies it.
Every change returns the diff, including in non-production environments.
No lost updates. Writes carry the configuration version they read, so a concurrent edit is reported instead of overwritten. Environments that require a reason need one on every change.
Visible in the audit log. Requests from the MCP server carry the user agent darkship-mcp/<version>; the console marks those events with a via MCP badge and the audit_log tool can filter them.
Same limits as the API. Rate limits, quotas and tenant isolation are enforced by the API for each token.

Example requests#

Outputprompts

Which flags in the "checkout" project are enabled in prod?
Turn off "new-pricing-page" in staging and show me the diff.
Roll "search-v2" out to 20% in staging, 50/50 on the "beta" variation.
What would user id 42 in the US get for "new-pricing-page" in prod?
Show the audit events from the last day made through MCP.

Troubleshooting#

Symptom	Cause
`401` on connect	Missing, malformed, revoked or expired token. Create a new one in the console.
A tool is missing from the list	The token lacks its scope, or is limited to other projects or environments. `whoami` shows what the token has.
"repeat with confirm: true"	The target is a production or protected environment. Review the diff, then confirm.
`429`	API rate limit for the token. The error carries the retry delay.

The REST API behind the server is described in the API reference, and to add flag evaluation to an application instead, see Build with AI.

Was this helpful?