Integrations

Use Protoline With MCP

Connect an MCP client to Protoline to create, edit, and deploy projects.

Quickstart

Use a Protoline account with access to the projects you want to operate and an MCP client that supports Streamable HTTP OAuth.

Run the Protoline npm setup helper for your client:

npx -y @protoline/protoline bootstrap --client codex
npx -y @protoline/protoline bootstrap --client claude
npx -y @protoline/protoline bootstrap --client all

For Codex, the helper configures the hosted MCP server and starts OAuth. For Claude Code, it configures the hosted HTTP MCP server; Claude Code starts OAuth inside Claude Code when the server is used or shown as needing authentication.

Use --no-login when you want to configure the server without immediately starting OAuth:

npx -y @protoline/protoline bootstrap --client codex --no-login
npx -y @protoline/protoline bootstrap --client claude --no-login
npx -y @protoline/protoline bootstrap --client all --no-login

The package installs lightweight client skills for deterministic Protoline shortcuts where the client supports them. Use --no-skills to configure only the MCP server.

Run local setup diagnostics with:

npx -y @protoline/protoline doctor

It does not run a local MCP server. The helper configures Protoline's hosted MCP server, and installed skills are optional shortcuts over the MCP tools.

Example requests

After connecting the MCP server, natural language works in any client:

List my Protoline projects.
Create a new project named Operations Portal in my Platform team.
Show the latest failed change request for the billing portal.
Read the deployment logs for the latest dev deploy.
Create a Protoline change to add CSV export to the dashboard.
Show me the diff for that change request.
Publish the reviewed change to production.
Promote the reviewed change to production.

Claude Code can expose the installed Protoline skill as slash commands after you restart Claude Code:

/protoline
/protoline new
/protoline publish
/protoline promote
/protoline login

Codex skills are not slash commands. In Codex, use $protoline or natural language:

$protoline
$protoline new
$protoline publish
$protoline promote
$protoline login

What MCP access does

Protoline exposes an HTTP MCP endpoint for clients such as Claude Code and Codex. The MCP server lets an authenticated user inspect project state, read source snapshots, review diffs and logs, create or amend change requests, retry failed workflows, and publish reviewed changes.

MCP access is a control-plane integration. It does not give the client shell access, Docker access, database access, or direct filesystem access to your runner host. Code changes still go through Protoline change requests and the runner workflow.

Connect Codex manually

Add the hosted MCP server and start OAuth:

codex mcp add protoline \
  --url https://app.protoline.ai/api/mcp \
  --oauth-resource https://app.protoline.ai/api/mcp

codex mcp login protoline \
  --scopes project:read,project:create,project:write,deployment:write

Connect Claude Code manually

Add the hosted HTTP MCP server:

claude mcp add --transport http protoline https://app.protoline.ai/api/mcp

Claude Code supports OAuth discovery and dynamic client registration for remote HTTP MCP. If claude mcp list shows Protoline as needing authentication, open Claude Code and complete the client authentication flow there.

Scopes

OAuth clients request the scopes that match the actions you want the MCP client to perform:

Scope	Allows
`project:read`	List projects, read status, files, diffs, activity, and logs
`project:create`	List organizations and teams, and create new projects
`project:write`	Create, amend, and retry change workflows
`deployment:write`	Publish reviewed changes, retry production deploys, and stop environments

Scopes are not a replacement for organization permissions. Protoline checks both the token scope and your normal project role before executing a tool.

Available tools

The MCP server exposes project tools for common Protoline workflows:

Tool	Use
`protoline_help`	Show focused MCP help
`list_organizations`	Find organizations available to the token owner
`list_teams`	List teams in an organization before creating a project
`create_project`	Create a new empty Protoline project
`list_projects`	Find projects available to the token owner
`read_project_status`	Read source, deployment, build, and change-request status
`list_files`	List files in the current source snapshot
`read_file`	Read a bounded file by repository-relative path
`list_change_requests`	List recent change requests
`read_change_request`	Inspect one change request and its workflow steps
`read_diff`	Read a bounded change-request diff
`read_project_activity`	Read normalized project activity
`read_logs`	Read bounded logs through an opaque log reference
`create_change`	Create a runner-backed change request from a prompt
`amend_change`	Add instructions to an existing change request
`retry_import`	Retry a failed source import
`retry_change`	Retry a failed editor run
`retry_production`	Retry a failed production deployment
`publish_change`	Publish a reviewed change and queue production deployment
`promote_change`	Same behavior as `publish_change`
`stop_environments`	Stop active project environments

Project-scoped tools require a project_id. Use list_projects first if you do not know the project ID.

create_project creates the project record for an explicit team_id and applies that team's deployment target defaults. It does not upload source files, import a ZIP, or import a local checkout.

Skills and Shortcuts

The npm setup helper installs a small protoline skill for supported clients. That skill gives deterministic shortcuts for the common command surface:

Shortcut	Behavior
`protoline`	Show Protoline MCP help
`protoline new`	Create a new empty project
`protoline publish`	Publish a reviewed change to production
`protoline promote`	Same behavior as `protoline publish`
`protoline login`	Point back to `bootstrap` for first-time setup or `login` for re-authentication

Claude Code exposes installed skills as slash commands, so /protoline can work there after restarting Claude Code. Codex skills are not slash commands: Codex intercepts unknown / commands before skills run. In Codex, use $protoline or natural language such as "Show Protoline help."

Use natural language for status, files, diffs, activity, logs, retries, and change requests. Those actions remain available as MCP tools without making every tool a command-menu item. Removing installed skills should not break MCP access; they are shortcuts, not the source of authority.

Security model

OAuth MCP requests run as the signed-in user who approved the MCP client. Mutating actions are recorded as MCP-triggered Protoline actions, and credential usage is tracked.

The MCP server intentionally does not expose general-purpose shell, Git, Docker, or database tools. It also does not allow direct pushes to main or bypass review. Source changes should be requested through create_change or amend_change, reviewed, and published through the normal Protoline workflow.

If an OAuth MCP client should no longer have access, revoke its OAuth session in the Protoline profile page.

Troubleshooting

If the client cannot connect, verify that the URL is https://app.protoline.ai/api/mcp.

If Codex does not request a resource-bound OAuth token, remove and re-add the server with --oauth-resource https://app.protoline.ai/api/mcp.

If a tool returns project_id is required, call list_projects and retry with the project ID.

If a tool returns Forbidden, the token is missing a required scope or your Protoline role does not include the required project permission.