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
Authorizationheader.
1. Create an API Client
- In Blue Canvas, click your avatar in the top right, then click your name.
- Open Developers.
- In API Clients, click Create Client. A new row appears right away.

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:
| Setting | Value |
|---|---|
| URL | https://mcp.bluecanvas.io/mcp |
| Transport | Streamable HTTP |
| Header | Authorization: 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
devanduatundersrc/classes?" - "Why did the last validation of deployment 123 fail?"
- "Create a draft deployment from
devtouatwith the changed Apex classes."
What the agent can do
| Area | Tools |
|---|---|
| Branches and files | list_branches, list_files, get_file, list_commits, get_file_diff, compare |
| Deployment requests | list_deployments, get_deployment, get_deployment_file, create_deployment, update_deployment, set_override, revert_override, list_permissions |
| Comments | list_comments, create_comment, reply_to_discussion, update_comment, delete_comment, resolve_discussion |
| Syncs | list_syncs, get_sync_logs, request_sync |
| Activity | list_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_permissionsshows which ones could be included. - Older drafts cannot be opened. Drafts saved before drafts were numbered appear in
list_deploymentswithnumber: null. Open those in Blue Canvas. - The activity feed is slow.
list_activitycan 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_syncqueues a sync but does not return the sync it becomes. Look for it withlist_syncs. list_syncscannot 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 see | What 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 tool | Your user lacks the permission for that action on that branch. Ask a workspace owner. |
| A tool mentioned here is missing | Restart your client so it reads the current list of tools. |
Claude Code: MCP server bluecanvas already exists | A 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].
Updated about 22 hours ago
