Connect AI agents with the Blue Canvas MCP server

Let an AI agent read your Blue Canvas workspace and prepare deployment requests, using the Model Context Protocol (MCP). Currently in beta.

🚧

Beta

The Blue Canvas MCP server is in beta. Tools and their behaviour may change, and there are known limitations. Tell us what works, what breaks and what is missing at [email protected].

The Blue Canvas MCP server lets an AI agent work with your workspace: compare orgs, read metadata, look at syncs, and create and review deployment requests. It speaks the Model Context Protocol (MCP), so it works with any MCP client that can connect to a remote server and send a custom header.

The agent acts as you. It connects with an API Client that belongs to your user, so it can see and do what you can, and nothing more.

What you need

  • A Blue Canvas user.
  • An MCP client that supports remote servers over Streamable HTTP and lets you set an Authorization header.

1. Create an API Client

  1. In Blue Canvas, click your avatar in the top right, then click your name.
  2. Open Developers.
  3. In API Clients, click Create Client. A new row appears right away.

The API Clients section with one client

Each client has an ID and a Secret, each with a copy button. The secret stays hidden unless you click the eye icon. You will need both in the next step.

If the ID and Secret columns look squeezed, widen the browser window.

Treat the secret like a password. Anyone who has the ID and the secret can act as you in Blue Canvas. To revoke a client, click Delete in its row.

2. Build the credential

The server expects the ID and secret as an HTTP Basic credential: the two joined by a colon, base64-encoded.

Keep it in an environment variable instead of writing it into your client's configuration. A client stores whatever it is given and shows it back, so a credential pasted into the configuration can end up in your terminal and in your agent's transcripts.

Add this line to your shell profile (for example ~/.zshrc), with your own ID and secret in place of the two placeholders:

export BLUECANVAS_MCP_BASIC="$(printf '%s:%s' 'YOUR_CLIENT_ID' 'YOUR_CLIENT_SECRET' | base64 | tr -d '\n')"

Then open a new terminal, or run source ~/.zshrc, so the variable is set.

3. Connect your MCP client

Add a remote MCP server to your client with these settings:

SettingValue
URLhttps://mcp.bluecanvas.io/mcp
TransportStreamable HTTP
HeaderAuthorization: Basic <your credential>

Where your client can read a header value from an environment variable, point it at BLUECANVAS_MCP_BASIC rather than pasting the value. Your client's documentation says how to add a remote server and its headers.

Example: Claude Code

claude mcp add --transport http bluecanvas https://mcp.bluecanvas.io/mcp \
  --header 'Authorization: Basic ${BLUECANVAS_MCP_BASIC}'

Keep the single quotes. They make Claude Code store the text ${BLUECANVAS_MCP_BASIC} and fill in the value each time it connects, so the configuration holds no secret. claude mcp get bluecanvas then reports Status: ✔ Connected.

4. Check the connection

You can test the server and your credential without any client. This asks the server for its list of tools:

curl -s https://mcp.bluecanvas.io/mcp \
  -H "Authorization: Basic ${BLUECANVAS_MCP_BASIC}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A JSON response that lists tools such as list_branches means the credential works. An error means it does not: see Troubleshooting.

5. Try it

Ask your agent something that needs your workspace:

  • "Which branches are connected to Blue Canvas?"
  • "What differs between dev and uat under src/classes?"
  • "Why did the last validation of deployment 123 fail?"
  • "Create a draft deployment from dev to uat with the changed Apex classes."

What the agent can do

AreaTools
Branches and fileslist_branches, list_files, get_file, list_commits, get_file_diff, compare
Deployment requestslist_deployments, get_deployment, get_deployment_file, create_deployment, update_deployment, set_override, revert_override, list_permissions
Commentslist_comments, create_comment, reply_to_discussion, update_comment, delete_comment, resolve_discussion
Syncslist_syncs, get_sync_logs, request_sync
Activitylist_activity

The tools are built on the Blue Canvas REST API. If you would rather call it from your own code, see the API reference.

  • Permissions are yours. Creating or editing a deployment request needs permission to create deployments into its target branch. Requesting a sync needs the branch's Manage Sync permission.
  • New deployment requests are drafts unless the agent is asked to submit them. Submitting starts packaging and validation against the target org.
  • Comments can be edited or deleted only by their author.
  • Large results come in pages. Comparisons and directory listings return 200 rows at a time, and a file is read 2,000 lines at a time. The agent asks for the next page when it needs it.

Known limitations

The server is in beta. These are the limits we know about today:

  • No deploying, deleting or completing. An agent can prepare a deployment request, edit it, comment on it and read its validation results. A person deploys, deletes or completes it in Blue Canvas. This is deliberate for the beta.
  • No OAuth sign-in. The server accepts an API Client credential only. Clients that can connect only through an OAuth sign-in, such as custom connectors on claude.ai, are not supported yet.
  • Deployment requests are STORY or CHECKLIST. An agent cannot create releases or permissions-only deployment requests, and cannot add Profiles or Permission Sets to a deployment request. list_permissions shows which ones could be included.
  • Older drafts cannot be opened. Drafts saved before drafts were numbered appear in list_deployments with number: null. Open those in Blue Canvas.
  • The activity feed is slow. list_activity can take close to a minute for a workspace with a long history, and may ask the agent to retry.
  • A sync request cannot be followed. request_sync queues a sync but does not return the sync it becomes. Look for it with list_syncs.
  • list_syncs cannot filter by outcome. It filters by sync type only, so finding failed syncs means paging through the list.
  • New tools need a reconnect. Clients read the list of tools when they connect. Restart your client to pick up tools added since.

Hit something that is not on this list? Write to [email protected].

Troubleshooting

What you seeWhat to do
Missing or malformed Basic credentials (HTTP 401)The header is missing or empty. If you use the environment variable, it is not set where your client runs: echo ${#BLUECANVAS_MCP_BASIC} should print a number greater than 0. Open a new terminal after editing your shell profile.
Invalid client credentials (HTTP 401)The ID or secret is wrong, or the API Client was deleted. Copy both again from Developers and rebuild the credential.
Permission denied from a toolYour user lacks the permission for that action on that branch. Ask a workspace owner.
A tool mentioned here is missingRestart your client so it reads the current list of tools.
Claude Code: MCP server bluecanvas already existsA server with that name is already configured for this project. Remove it with claude mcp remove bluecanvas, or add this one under another name.

Still stuck? Write to [email protected].