# BCMS MCP Server

The BCMS MCP server gives agents live access to your CMS: templates, groups, widgets, entries, media, languages, statuses, entry history, and schema operations. Access is limited to the permissions attached to the MCP key.

## Connection

- Endpoint: `https://app.thebcms.com/api/v3/mcp?mcpKey=YOUR_MCP_KEY_HERE`
- Transport: Streamable HTTP
- Authentication: mcpKey query parameter: a three-part BCMS API key (keyId.secret.instanceId) with the MCP flag enabled; the endpoint returns 403 otherwise. Send the mcp-session-id header on follow-up requests after initialize.

### Client config (Cursor, Claude Code, and other JSON-config clients)

```json
{
  "mcpServers": {
    "bcms": {
      "url": "https://app.thebcms.com/api/v3/mcp?mcpKey=YOUR_MCP_KEY_HERE"
    }
  }
}
```

### Claude Code CLI

```bash
claude mcp add --transport http bcms "https://app.thebcms.com/api/v3/mcp?mcpKey=YOUR_MCP_KEY_HERE"
```

## Create a scoped key

1. Open the BCMS dashboard and go to Settings, then MCP.
2. Create a key and scope it to the templates and media the agent needs.
3. Copy the three-part key (keyId.secret.instanceId) into your client config.
4. After initialize, MCP clients must send the mcp-session-id header on follow-up requests (handled automatically by most clients).

## Capabilities

| Area | What it does | Tools |
| --- | --- | --- |
| Templates | List, read, create, update, and delete templates. | get-all-templates, get-template-by-id, create-template, update-template, delete-template-by-id |
| Entries | Full CRUD on entries per template. | get-all-entries-by-template-id, get-entry-by-id, create-entries, update-entries, delete-entries |
| Entry statuses | Manage entry statuses (draft, published, custom). | list-entry-statuses, get-entry-status-by-id, create-entry-status, update-entry-status, delete-entry-status-by-id |
| Entry history | Read the change history of entries. | get-all-entry-history-items, get-entry-history-items-for-entry, get-entry-history-by-id, get-entry-history-file-data |
| Groups | Manage reusable field groups. | get-all-groups, get-group-by-id, create-group, update-group, delete-group-by-id |
| Widgets | Manage content widgets. | get-all-widgets, get-widget-by-id, create-widget, update-widget, delete-widget-by-id |
| Languages | Add, list, update, and delete instance languages. | get-all-languages, get-available-languages, get-language-by-id, add-language, update-language, delete-language-by-id |
| Media | Browse media, create folders, and request upload URLs. | get-all-media, get-media-by-id, list-media-directories, create-media-directory, request-upload-media-url |
| Pointer links | Resolve internal links to entries and media. | get-entry-pointer-link, get-media-pointer-link |
| Trash | Inspect trashed items. | get-all-trash-items, get-trash-item-by-id, get-trash-item-file-data |

## Recommended path

1. Install the bcms skill
2. Create a scoped key in the BCMS dashboard
3. Connect the MCP server in your client
4. Ask the agent to inspect available templates

## Security

- Create separate credentials per person, per client, and per environment.
- Scope keys to the templates the agent needs (least privilege), including media-level permissions.
- Never put MCP keys or BCMS_API_KEY in frontend code, public repos, or shared screenshots.
- Rotate keys regularly and revoke any key immediately if it is exposed.
- Review entry history to audit what an agent changed.
- For destructive operations, list and confirm entry ids first and use scoped delete permissions.

## Troubleshooting

- **The endpoint returns 403.** The key does not have the MCP flag enabled, or the key is wrong. Create an MCP key in the dashboard under Settings, then MCP.
- **Tools do not appear in Cursor.** Restart MCP or reload the window. Check that the URL contains your real key, not the placeholder.
- **A tool call fails with a permission error.** The key is missing a scope for that template or media. Update the key permissions in the dashboard.
- **Environment variables in Cursor mcp.json are not expanded.** Cursor does not consistently expand env vars in MCP server URLs. Paste the key into local, user-level config instead.

## More

- [MCP documentation](https://thebcms.com/docs/getting-started/mcp.md)
- [Security and permissions](https://thebcms.com/docs/getting-started/mcp.md#security--permissions)
- [Agent onboarding hub](https://thebcms.com/agents.md)
- [Agent Skills](https://thebcms.com/agent-skills.md)