# Conductor — how to use (mcp.ai)

Connect your Conductor account and use 17 tools for AI agents straight from your AI agent. Connect with your own API key. Conductor is a cloud development platform for creating workspaces, running coding-agent sessions, exchanging messages, and searching session transcripts.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_conductor?ms=1787291520000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `conductor_change_workspace_state`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/conductor`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/conductor/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/conductor/change/workspace/state` — Put a workspace to sleep or archive it. Both actions stop active workspace use; archive is a stronger transition but is documented as restorable. Confirm the intended target and state before calling.
  - body: { action: string, workspace_id: string }
- `POST https://api.mcp.ai/api/conductor/create/session` — Create another agent chat session in an existing workspace. This may start agent/model resources and incur charges; call only when the user explicitly intends a new session.
  - body: { name?: string, agent: string, model?: string, effort?: string, channel?: string, fast_mode?: boolean, session_id?: string, workspace_id: string }
- `POST https://api.mcp.ai/api/conductor/create/workspace` — Create a cloud workspace and its first agent session. This launches compute and may incur cloud or model charges; call only when the user explicitly intends to create a new workspace.
  - body: { env?: object, name?: string, agent?: string, model?: string, branch?: string, effort?: string, channel?: string, project_id?: string, session_name?: string, repository_url?: string }
- `POST https://api.mcp.ai/api/conductor/get/current/user` — Return the user and organization represented by the connected Conductor API key. Use this to verify which account the connection acts as.
- `POST https://api.mcp.ai/api/conductor/get/message` — Get one transcript message by id. The content may contain sensitive prompts, agent output, configuration, or provider-specific events.
  - body: { message_id: string }
- `POST https://api.mcp.ai/api/conductor/get/project` — Get one Conductor project and its repository remote by project id.
  - body: { project_id: string }
- `POST https://api.mcp.ai/api/conductor/get/session` — Get one agent session's configuration and current idle, working, or error status in one read. The tool fails unless both records are retrieved and refer to the requested session.
  - body: { channel?: string, session_id: string }
- `POST https://api.mcp.ai/api/conductor/get/workspace` — Get a workspace's metadata and current lifecycle status in one read, including initialization progress or errors. The tool fails unless both records are retrieved and refer to the requested workspace.
  - body: { channel?: string, workspace_id: string }
- `POST https://api.mcp.ai/api/conductor/list/messages` — Read one page of a session transcript or incrementally read messages after a known message ID. Returned content may contain sensitive user prompts, agent output, configuration, or provider events; req
  - body: { limit?: integer, offset?: integer, session_id: string, after_message_id?: string }
- `POST https://api.mcp.ai/api/conductor/list/projects` — List repositories available to the connected account for creating Conductor workspaces.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/conductor/list/sessions` — List one page of agent chat sessions in a Conductor workspace.
  - body: { limit?: integer, offset?: integer, channel?: string, workspace_id: string }
- `POST https://api.mcp.ai/api/conductor/list/workspaces` — List one page of workspaces belonging to a Conductor project, including deep links and recent activity.
  - body: { limit?: integer, offset?: integer, channel?: string, project_id: string }
- `POST https://api.mcp.ai/api/conductor/query/transcripts` — Run one read-only SQL SELECT against the organization's session_transcripts_view. Results can expose sensitive transcript text across many sessions: select only necessary columns, constrain rows with 
  - body: { query: string }
- `POST https://api.mcp.ai/api/conductor/rename/session` — Change an existing Conductor session's display name without stopping its agent.
  - body: { name: string, channel?: string, session_id: string }
- `POST https://api.mcp.ai/api/conductor/rename/workspace` — Change the display name of an existing Conductor workspace without changing its lifecycle state.
  - body: { name: string, channel?: string, workspace_id: string }
- `POST https://api.mcp.ai/api/conductor/send/message` — Send a prompt to a Conductor session agent. This can start external agent/model execution and incur charges; it is not a passive transcript append. Call only when the user intends the agent to act.
  - body: { message: string, message_id?: string, session_id: string }
- `POST https://api.mcp.ai/api/conductor/stop/session` — Cancel only the current turn and queued messages, or archive the entire session. Both can discard queued work; archive also stops the agent and leaves the session read-only. Confirm the intended actio
  - body: { action: string, session_id: string }

## Example prompts
- "What can I do in Conductor?"
- "Show me a summary of my Conductor account"

## More
- Page: https://mcp.ai/conductor
- Agent spec (llms.txt): https://mcp.ai/conductor/llms.txt
- Postman collection: https://mcp.ai/conductor/postman.json