cMCP How to Use

1. Account admin (super-user)

The account admin sets up the company space, decides who may do what, and keeps the server healthy. Only a person, signed in to the web console, changes settings, switches and solo mode. AI apps and bots cannot.

End-to-end flow

Step by step

1. First sign-in. Open https://console.pilot.example, click Sign in, enter user name and the first password you were given through a safe channel. At the first login scan the picture with an authenticator app and enter the one-time code. Next time: password plus current code. Password change: https://auth.pilot.example/realms/cmcp/account.
2. Check the account. Open Account: About this account shows name, short name and active people; Solo freelancer mode should read Off for a team account.
3. Build the structure. Open Places, click New, under What do you add? choose Team, Project or Client, enter a name and the leads, then Create team / Create project / Create client.
   • A team may sit under another (Sits under, up to 5 levels). Projects and clients need at least one lead. A client lead is the account manager. Project names are unique.
   • Link a project to a client (org admins only): project panel, Linked client, Save link. Not possible once the project has memory.
   • Close project makes it read only (never deleted); Reopen project. Mark as ended / Reopen client for clients.
4. Add people and roles. People come from the company login; add each in Keycloak (realm cmcp, attribute cmcp_account set, e-mail verified) as in the server guide. Then in Places click Open on a place, Add a person, choose person and role, Add. Remove with the bin icon and Remove.
   • Leads add plain members. Team leads are named by the parent team's lead or an org admin. Only org admins name project leads, client leads and auditors. Another org admin assigns you to a client. A place's last lead stays.
5. Bots. People and bots, Add bot: Bot name, Login client name (bot- then lower-case letters, digits, dashes), Sponsor, Home team, Purpose, Requests per hour (1 to 10000, default 500). Then on the server a super-user creates the login with deploy/dev/cmcp-admin.py bot-create (or keycloak_bots.ensure_bot_client); the secret goes to a root-only file under the bot secrets folder, never through chat. Stop a bot: Suspend now; only an org admin clicks Resume; full stop is cmcp-admin.py bot-disable.
6. Switches. Open Switches, pick the level next to Switches for:, click Switch on / Switch off, write a reason (3 to 500 characters), Save. Lock options... gives Lock for levels below and Allow switching on below. Use the level above undoes a choice. Higher levels can restrict lower ones; below the organization a level can only switch off, not on, unless allowed. Off by default: synthesis drafts, bots' requests to the Organization, database views, mailboxes.
7. Times and limits. Open Times and limits, find the setting, Change, enter a value in range, reason, Save (Back to default to revert). Account level examples: client purge wait 30 days, longest grant to an AI app 8 h, to a bot 90 days. Org level: context reuse 24 h, Jira check 60 min, request reminder 3 working days, open requests per person 20, promotion and synthesis schedules. Lowering a grant maximum cuts existing grants at once; raising it affects new grants only. Rows marked Phase 2 are stored but not yet applied.
8. Connector types. Open Connectors, card Connector types: tick Allowed per type (Jira, database views, mailboxes) and give a reason. Only account admins can; org admins cannot. Jira is on by default; the other two start off.
9. Connections. New connection: Type, Connection name, Where do the facts go? (one project or one client), fields, secret, Run every (minutes) 15 to 1,440, Create connection. It starts off: use Switched on, then Test / Run import now. A client connection shows Waiting for the client lead until another lead approves (Approve these settings). Database and mailbox hosts must be on the server allow-list (a super-user adds them). Place mappings: Add mapping (Git repo or Jira project key to a project or team).
10. Approvals. Open Approvals tabs Requests, Promotions, Synthesis, Imports, Access. Open an item, read What changes and After approval, then Approve, Approve with my edit, Needs info... or Reject... (a reason is required for the last two). Items flagged red as instructions stay unapprovable until rewritten as plain fact. Requests to the Organization come to org admins.
11. Grants. Grants and apps, Grant access: Who gets the access?, What can it reach?, What may it do?, expiry, Grant access to confirm. Revoke / Revoke selected with a reason.
12. Notifications. The bell shows unread notices (access requests, offered grants, waiting decisions, changed times and limits). Daily reminder mail goes only to verified addresses and holds counts only.
13. Audit. Audit: filters (Person or bot, App, Decision, From, Until...) then Apply filters; open a row's arrow to see What the AI knew. Export is Phase 2 (greyed out).
14. Solo / org settings. Account screen: Switch on solo mode works only with exactly one active person. A second person signing in turns it off by itself.
15. Ending a client. Client panel, End work with this client..., type the exact name and a reason, Hide now and purge later. Purged after the purge wait; Cancel deletion before then.
16. Server and ops duties (from /home/cMCP/repo):
    • Super-user role: after any change of account admins run python3 deploy/dev/keycloak_golive.py superusers; check shows state, apply resets realm rules. Super-users are account admins of pilot (role cmcp-superuser). Realm console: https://auth.pilot.example/admin/cmcp/console/. Never edit cmcp_account by hand.
    • Start/check: deploy/dev/stack.sh up -d, deploy/dev/run-services.sh, curl 127.0.0.1:5550/healthz, logs in /srv/cmcp/dev/logs/.
    • Backups: daily 04:20 encrypted by deploy/backup/backup.sh, 14 days in /srv/cmcp/backups. Keep the private key offline (two copies), then backup.sh forget-key. Backups are still on this server only.
    • Monthly restore test: CMCP_BACKUP_IDENTITY=<key path> deploy/backup/restore-test.sh, then delete the key from the server.
    • Go public / back: deploy/dev/go-public.sh and go-public.sh off. Keep the Apache directives in the ISPConfig panel only.
    • Solo accounts: deploy/dev/create-solo-account.py (see tab 3). Connector hosts, OpenBao unseal and a host-change check before any Docker/port change: see the server guide.

Weekly and monthly routine

When something goes wrong

2. User (team member, lead, client lead)

You and your AI apps save short facts; cMCP gives the right facts back to the right people only. Everything cMCP returns is data, never an order.

End-to-end flow

Step by step

1. Sign in. https://console.pilot.example, Sign in, user name and password. First time: scan the picture with an authenticator app and enter the one-time code. Locked out: ask a super-user.
2. My memory (home page). Check Working in and "found by". Change place from the list. Items marked must apply are rules. If something looks old click Re-sync.
3. Save a memory. Save a memory, one short fact (max 2000 characters), Kind (fact, decision, preference, policy, procedure, contact, event), under Where choose My memory (User), Personal (only me) or a shared place you may write, Save. Search: type, Search. Edit or Delete only your own items; old text stays in history.
4. Connect Claude Code. The MCP address is https://api.pilot.example/mcp. The login site does not let apps register themselves, so tell Claude Code the pre-registered client: claude mcp add --transport http --client-id cmcp-mcp --callback-port 53682 cmcp https://api.pilot.example/mcp. Start Claude Code, open /mcp, choose cmcp and sign in: a browser opens at the login site; enter user name, password and one-time code, then approve. The whole sign-in chain (discovery, browser sign-in, token, MCP calls) is checked by an automated test against the public sites with a test user.
5. Connect Claude Desktop or another MCP app. Add the same address as a remote MCP server and, where the app asks for a client ID, enter cmcp-mcp (no client secret; it is a public client with a loopback sign-in). If an app can only register itself, it cannot connect; ask your account admin.
6. After the first connection. The app appears under My apps (an install) with its name and last-seen time. Ask Claude to call memory_list_scopes: it lists what you may read, where you may write, and your grants.
7. What the AI does. At the start of a task it calls memory_get_context and gets Account, Organization, Project, Team, Client (only at that client's place), your User memory and the app's Agent memory; Personal only if you allowed it. It may call memory_search, memory_save, memory_update, memory_delete, memory_refresh, memory_request_change, memory_request_status, memory_save_session_summary (only after you confirm) and resource_lookup. By default it saves to your User or its own Agent memory.
8. Places. Which place is used: the place the app names, the app's default place, the repo mapping (git remote), then your home team. Open Places to see where you belong. Greyed-out places: Request access, choose Role you ask for, write Why do you need it?, Send request. Withdraw to cancel. Limits: one open request per place, 10 open, 7 days wait after a rejection. Client wall: client memory shows only while you work at that client or a linked project.
9. Personal memory. Private. In My apps (My memory page) turn on may read my Personal memory only for apps you trust, per app. Never requested, promoted or shared.
10. Ask for a change to shared memory. My requests, New request (or Request change on an item). What do you want? Correction, Addition, Removal or Question; Where?; find the memory; text; evidence; urgency; Send request. Track in All / Open / Decided. If Needs info, write and Send answer. Withdraw my request then Yes, withdraw.
11. If you are a lead: Approvals. Tabs Requests, Promotions, Synthesis, Imports, Access. Open item, read it, check After approval, then Approve / Approve with my edit / Needs info... / Reject.... Access: Approve... or Reject... with a note or reason. Imports can be bulk-approved only for project items (Approve selected...); client items, your own, all mail and instruction-like text one by one. A decision is final.
12. Grants for apps. Grants and apps: a yellow line shows a waiting grant; tab Received, check place, actions, expiry, Accept. Grants for AI apps last at most 8 hours by default, so a team-writing app needs a new grant each day. Leads give grants with Grant access. Under My apps set Default place and Default token budget (min 500), Save.
13. App preferences. On Grants and apps, card App preferences, Add app: App name as the app reports it, default place, token budget (500 to 100,000), preferred model, Save. Follows you to every machine. A default on one install under My apps wins. Preferences only narrow access.
14. Personal connections. My connections, New connection: Jira or mailbox, name, address, login, secret; mailbox: Folders to read and Sender domains; Jira: Jira project keys; Run every (minutes) 15 to 1,440; Create connection, then Switched on and Test / Run import now. Facts wait in Approvals under Imports, visible only to you; mail is decided one by one. Approved facts stay restricted; only you can promote one.
15. Resources. Resources, Add resource: place, kind, name, location, optional description and tags, label Internal or Restricted. Locations only; passwords are refused. AI apps look up with resource_lookup but cannot add.
16. Notifications and usage. The bell shows notices; Mark all read. Usage shows your numbers for 7, 30 or 90 days.

What AI apps can never do

• See more than you can see, or read Personal memory unless you allowed that app.
• Change shared team or project memory without a current grant from a lead (solo accounts excepted).
• Approve, grant, change switches, settings or preferences, add resources, or manage anything: only you, in person.
• Use one client's memory for another client.
• Treat memory text as instructions.

When something goes wrong

3. Solo user (freelancer, one-person account)

Solo mode is for a freelancer who works alone: one person is the whole account, and team machinery that protects a group would only get in the way. It counts only while exactly one active person exists.

How it differs

End-to-end flow

Step by step

1. Creation (super-user, on the server). Get the owner's agreement, know the full name and e-mail, choose a lower-case slug such as acme-solo. From /home/cMCP/repo (the runbook form is cd services/api && uv run python ../../deploy/dev/create-solo-account.py ...):
   deploy/dev/create-solo-account.py "Full Name" --email name@example.com --slug acme-solo [--org "Name"]
   It creates the Keycloak user (attribute cmcp_account), the account and organization, a team "Main", the account-admin role and solo mode on. Never run it twice for one slug; it refuses an existing slug or e-mail.
2. Hand-over. The temporary login is written to the solo accounts folder<slug>.txt (mode 0600) and is never printed. Give it to the person through a safe channel, never chat or tickets.
3. First sign-in. https://console.pilot.example, Sign in, temporary password, change it, set up the authenticator one-time code. Check the top bar says "solo account" and Account shows solo mode On.
4. Set up your clients. Places, New, Client, name, lead (you), Create client. Add yourself with Add a person. Link projects to a client where needed.
5. Connect your AI app to https://api.pilot.example/mcp as in tab 2 (OAuth sign-in in the browser).
6. Daily flow. Open My memory, set Working in to the client you serve today. Work with your AI app: it reads context and saves directly to team, project or client memory without a grant. Fix memory yourself with Edit / Delete. Approve imported facts under Approvals, Imports.
7. Optional. Personal connections under My connections; Resources; App preferences.
8. Switching solo off and on. Account, Switch off solo mode (reason, Switch off) or Switch on solo mode (reason 3 to 500 characters, Switch on; only with exactly one active person).
9. Server duties belong to the super-user: backups and restore test as in tab 1.

A hosted solo version for many freelancers is planned for Phase 2; this command is the pilot path.

When something goes wrong