Skip to content

All articles

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

  1. Open the user menu → Profile → MCP Agent Access.
  2. Under Create token, enter a Name (for example Cursor laptop).
  3. Pick Scopes (see below). The default is read-only.
  4. Click Create token.
  5. 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 signals
  • calendar:read / calendar:write — content calendar
  • content-marketing:read / content-marketing:write — campaigns, plans, tasks, sales funnels
  • content-optimization:read / content-optimization:write — SEO keywords, Search Console, site scans, optimization reports
  • development:read / development:write — projects, repositories, business models
  • youtrack:read / youtrack:write — YouTrack Gantt
  • crm:read / crm:write — leads, opportunities, contacts, organizations
  • crm:delete — permanent CRM deletion (separate from crm:write)
  • finance:read / finance:write — budgets and transactions
  • facilities:read / facilities:write — facilities and security reports
  • settings: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_lead removes the lead, its contacts, interactions, opportunities and opportunity line items. Linked projects are kept.
  • delete_crm_contact removes only that contact, not its owner.
  • delete_crm_opportunity removes the opportunity and its line items, keeping the lead and linked project.
  • delete_crm_person removes the person and contacts; linked application identities are kept with the person link cleared.
  • delete_crm_organization and delete_crm_counterparty remove 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.

Articles