Connect an AI assistant to your workspace

An AI assistant can manage your employee list for you. You can ask Claude, Cursor or Copilot things like “who hasn’t accepted their invitation yet?” or “invite these three people”. The assistant connects to Spherum over the Model Context Protocol (MCP) with an API key, the same kind of key an HR system uses.

This page is the API-key setup, for local tools and integrations. To connect Claude or ChatGPT by signing in as yourself, with no key, see Connecting Claude or ChatGPT.

What the assistant can do

Action	What it does
Search employees	Lists people with their status: not invited yet, invited, granted access, or closed access
Invite a person	Creates a record and emails the person an invitation
Invite a batch	Up to 20 people at once; emails them only if you ask
Re-send an invitation	Emails the invitation again to someone who hasn’t granted access
Archive an employee	Marks someone as having left; frees their seat and ends your access to their card
Restore an employee	Brings an archived record back, for someone who returned

The assistant never sees what is on anyone’s card, so no emergency contact reaches it. It cannot revoke access either, because only the person can close their own card. Inviting and archiving affect real people, so keep your assistant’s confirmation prompts on and read what it proposes before you approve.

Before you start

1. Create a key. In the Portal, go to Settings → API keys → New key. Only administrators can do this. Name the key after the person and the assistant, for example “Mary — Claude Desktop”.
2. Copy it right away. The key is shown once. The same window also has Connect an AI assistant with this key, with the setup below already filled in for each assistant.
3. Treat the key like a password. It acts for your whole company. Give each person their own key, so one can be revoked without breaking the others.

The server address is https://api.spherum.ae/api/public/v1/mcp. It is also shown on the API keys page.

Claude Desktop

1. Install Node.js 18 or later from nodejs.org, if your computer doesn’t have it.
2. In Claude Desktop, open Settings → Developer → Edit Config. Paste the text below into the file and replace <YOUR_API_KEY> with your key. If the file already lists other servers, add spherum next to them.
3. Save the file and restart Claude Desktop.

{
  "mcpServers": {
    "spherum": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.spherum.ae/api/public/v1/mcp", "--header", "Authorization:${SPHERUM_AUTH}"],
      "env": { "SPHERUM_AUTH": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Claude Desktop’s Add custom connector button doesn’t work with Spherum yet, because it only supports servers that sign in with OAuth. Use the config file above instead.

Claude Code

Run this in a terminal, with your key in place of <YOUR_API_KEY>:

claude mcp add --transport http --scope user spherum https://api.spherum.ae/api/public/v1/mcp --header "Authorization: Bearer <YOUR_API_KEY>"

Spherum is then available in every project you open with claude.

Cursor

1. Open Cursor Settings → MCP → Add new global MCP server. This opens ~/.cursor/mcp.json.
2. Paste the text below with your key in place of <YOUR_API_KEY>. If the file already lists other servers, add spherum next to them.
3. Save the file. Spherum appears in the MCP list.

{
  "mcpServers": {
    "spherum": {
      "url": "https://api.spherum.ae/api/public/v1/mcp",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

Use the global file in your home folder, not a .cursor/mcp.json inside a project. A project file can end up shared or committed, and your key would go with it.

VS Code (GitHub Copilot)

1. Open the Command Palette and run MCP: Open User Configuration.
2. Paste the text below. If the file already lists other servers, add spherum next to them.
3. Start the server from the file. VS Code asks for your API key once and stores it securely, so the key never sits in the file.
4. Use Spherum from Copilot Chat in Agent mode.

{
  "inputs": [
    { "type": "promptString", "id": "spherum-api-key", "description": "Spherum API key", "password": true }
  ],
  "servers": {
    "spherum": {
      "type": "http",
      "url": "https://api.spherum.ae/api/public/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:spherum-api-key}" }
    }
  }
}

Check that it works

Ask your assistant:

Which employees haven’t granted access yet?

It should list people with the status Invited or NotActivated. A few more things you can ask:

• “Invite Mary Major, mary.major@example.com.”
• “Add these 12 people from the spreadsheet, but don’t email them yet.”
• “Re-send the invitation to everyone who was invited but hasn’t granted access.”
• “Richard Roe has left the company. Archive him.”

Not supported yet

• An API key in claude.ai or ChatGPT. Their connectors sign in instead: see Connecting Claude or ChatGPT.
• Reading cards, revoking access, the audit trail. These are not available to assistants, by design.

Keeping it safe

• Your key belongs in the assistant’s settings on your own computer. Never paste it into a chat, a shared document, or a file inside a project.
• If a laptop is lost or someone leaves, revoke their key in Settings → API keys. Their assistant stops working at once, and nothing else is affected.
• Everything the assistant does is done with your company’s key, exactly as if your HR system had done it.
• Claude Desktop logs what it sends to Spherum, including the names and email addresses of the people you ask it to invite, in a file in Claude’s logs folder on your computer. Keep that folder as private as the data itself.

Troubleshooting

What you see	What to do
“Unauthorized”	The key is wrong or was revoked, or Bearer is missing in front of it. Create a new key if needed.
“Too many requests”	The limit is 120 requests a minute from one network, shared with your other integrations. Wait a minute.
Spherum doesn’t appear in the assistant	Restart the assistant. If you added it next to other servers, check the commas in the file.
Claude Desktop: the server fails to start	Install Node.js 18 or later, then restart Claude Desktop.
“Validation failed” or “Request rejected”	The message says what was wrong, for example a sphere your company hasn’t purchased.

Building an integration

If you are writing code against the API rather than asking an assistant, give your coding tool this documentation and the specification instead: Using these docs with AI.