MCP Agent Access
Emperor has an MCP (Model Context Protocol) server. An AI agent such as Cursor or another MCP client can use it to read and change your workspace data. You do not need admin rights: every user sets this up in their own Profile.
Create a token
- Open the user menu → Profile → MCP Agent Access.
- Under Create token, enter a Name (for example
Cursor laptop). - Pick Scopes (see below). The default is read-only.
- Click Create token.
- Copy the token. It looks like
emp_<id>.<secret>and is shown once. Store it like a password.
A token:
- acts as you, with no more rights than your account has in the workspace;
- works only in the workspace that was active when you created it;
- expires after 90 days (the Expires column);
- stops working when you click Revoke or lose access to the workspace.
Edit scopes changes scopes on an existing token. The secret stays the same, so your client keeps working.
Scopes
Read scopes are on by default. Turn on a write scope only if the agent should create or change records.
signals:read— marketing signalscalendar:read/calendar:write— content calendarcontent-marketing:read/content-marketing:write— campaigns, plans, tasks, sales funnelscontent-optimization:read/content-optimization:write— SEO keywords, Search Console, site scans, optimization reportsdevelopment:read/development:write— projects, repositories, business modelsyoutrack:read/youtrack:write— YouTrack Ganttcrm:read/crm:write— leads, opportunities, contacts, organizationscrm:delete— permanent CRM deletion (separate fromcrm:write)finance:read/finance:write— budgets and transactionsfacilities:read/facilities:write— facilities and security reportssettings:read— settings reads (read-only; there is no write scope)
Secrets, OAuth credentials, token management, and project delete are never available through MCP.
Connect a client
The MCP endpoint is the Emperor MCP server at path /mcp (port 4477 on the Emperor host unless your administrator published another address). MCP Agent Access shows the address for your installation.
Send the token as a Bearer header. Example for Cursor (.cursor/mcp.json or the global MCP settings) and other clients that use the mcpServers format:
{
"mcpServers": {
"emperor": {
"url": "https://<emperor-host>:4477/mcp",
"headers": {
"Authorization": "Bearer emp_<id>.<secret>"
}
}
}
}
Replace <emperor-host> and the token with your values. If the client reports 401, the token is wrong, revoked, or expired. If a tool returns 403, the token lacks that scope or your role does not allow the action.
Delete CRM records
The following tools accept a record UUID in id:
delete_crm_leadremoves the lead, its contacts, interactions, opportunities and opportunity line items. Linked projects are kept.delete_crm_contactremoves only that contact, not its owner.delete_crm_opportunityremoves the opportunity and its line items, keeping the lead and linked project.delete_crm_personremoves the person and contacts; linked application identities are kept with the person link cleared.delete_crm_organizationanddelete_crm_counterpartyremove their contacts too (counterparty roles are also removed). An organization linked to projects, counterparties or workspace billing cannot be deleted. A counterparty linked to leads or business-model partners cannot be deleted.
Deletion is permanent. These tools require crm:delete and your account must be allowed to delete in that workspace. crm:write alone allows creating/updating, not deletion. New tokens remain read-only by default; enable crm:delete explicitly under Edit scopes when needed. When this feature is installed, only existing tokens with crm:write automatically receive crm:delete. Read-only tokens and tokens with write access only to other domains are unchanged. Secrets, expiry and revocation status stay the same. You can remove the scope afterwards; it is not automatically re-added.
The response is success: true with data.id and data.deleted counts: contacts, interactions, opportunities, lineItems and roles. A missing record (including one outside the workspace) returns 404 / not found; linked dependencies return 409. No partial deletion is saved on failure, and successful deletion is recorded in the audit log.