Plugins and MCP

Crewhall can be extended in three ways. Plugins add tabs, cards, commands and tools. MCP lets AI assistants such as Claude work in the workspace on your behalf. The REST API lets scripts and CI jobs call Crewhall with a personal token. All three act within the rights of a real person and never beyond them.

Plugins​

A plugin can add:

Crewhall never runs plugin code. A plugin's interface and logic run on its own server. Its tabs and cards open in a sandboxed frame, and every request Crewhall sends to the plugin is signed. When a plugin acts for a person, it can't do more than that person may do, and it is limited to the permissions the admin approved. Its messages and changes carry the plugin's badge.

Each plugin in the marketplace has a label: Official (made by the Crewhall team), Reviewed (reviewed and signed on the marketplace) or Unofficial (works in a way the connected service does not allow; the risks are listed before you install).

Install a plugin​

Org owners and admins manage plugins in Admin › Plugins.

1. Open the Marketplace tab and find the plugin.
2. Select Install. The dialog shows the plugin's server, the permissions it asks for and where it shows up.
3. Untick any permission you don't want to grant. The plugin is told what it got and works without the rest.
4. Select Approve permissions and install.

For a plugin that is not in the catalog, such as one private to your organization, use Install by ID or link and paste the plugin ID or the marketplace's install link.

Some plugins are marked Self-hosted. Your organization runs its own copy, so its data does not pass through the publisher's server. When you install one, enter your server's https address. That server must serve the manifest signed by the marketplace, with its own address, at /.well-known/crewhall-plugin.json. Crewhall checks it and then talks only to that address.

Manage installed plugins​

On the Installed tab you can:

• Turn a plugin on or off. While off, its tabs, cards and commands disappear.
• Change granted permissions with Permissions.
• Update to a new version. If it asks for more permissions, only the new ones are asked about.
• Remove it. Its server is told the installation was removed.
• Allow browser features such as microphone, camera, location or copy to clipboard. People still answer the browser's own prompt.

Some plugins can work in the background, for example to sync boards with another system. That needs the admin to grant it, and each person agrees separately. People turn it off in Notification settings › Plugins. Guests do not see plugins.

Server settings​

Plugins come from one marketplace. Two backend variables control it:

Every plugin package is checked against these keys on install and on every update. Unsigned plugins can't be installed.

Build a plugin​

The plugin SDK is @crewhall/plugin-sdk in packages/plugin-sdk. It is MIT licensed, so you can build and sell plugins freely. It has three parts:

The manifest declares the plugin ID (reverse domain, such as com.example.hello), version, name, publisher, its server address (origin), the permissions it asks for and its entry points. Permissions use the same scopes as MCP and personal tokens, such as hub:read and chat:send.

A minimal plugin page:

import { connect } from '@crewhall/plugin-sdk/bridge';

const bridge = await connect();
document.body.textContent = `Hello ${bridge.context.user.name}`;
const token = await bridge.getToken(); // send this to your plugin server

On your server, verify the session token. It is valid for 5 minutes and also opens the Crewhall REST API with the person's rights and the plugin's permissions.

import { verifySessionToken } from '@crewhall/plugin-sdk/server';

const who = await verifySessionToken(token, {
  issuer: installation.apiUrl,
  audience: 'com.example.hello',
});

Check your manifest, then send it to the marketplace for review. The marketplace signs the release when it is approved; developers do not sign packages themselves.

pnpm --filter @crewhall/plugin-sdk plugin validate manifest.json

apps/plugin-hello (also MIT) is a sample plugin that shows every entry point: a tab, a home card, a /hello command, a greet tool and a message.created event. Run it locally with:

PORT=4331 PLUGIN_ORIGIN=http://localhost:4331 pnpm --filter @crewhall/plugin-hello dev

MCP: connect an AI assistant​

Crewhall has a built-in MCP server at https://hub.example.com/mcp. It supports streamable HTTP, OAuth 2.1 with PKCE and dynamic client registration. Clients without OAuth can send a personal token in the Authorization: Bearer header. You find the address and setup steps in My account › MCP and API.

Claude Code:

claude mcp add --transport http crewhall https://hub.example.com/mcp

Then type /mcp in Claude Code and choose crewhall › Authenticate. The Crewhall consent screen opens in your browser.

Claude Desktop and claude.ai: go to Settings › Connectors, choose Add custom connector, paste the address, select Connect and allow on the consent screen. On team plans the org admin adds the connector first, then everyone connects with their own account.

Scopes and the consent screen​

On the consent screen you choose what the client may do, which spaces it may reach and how long the connection lasts (7, 30 or 90 days, or no expiry). Reading is always required. The client never gets more than you can do.

You can narrow or remove a connection any time in My account › MCP and API. Narrowing takes effect immediately.

Approvals​

Risky actions wait for a person. Depending on the organization's policy, these include moving items to the trash, bulk changes of 20 or more items, external share links, publishing to the portal and messages to space chats. Some of them always need approval.

Waiting requests appear in My account › Pending approvals with a preview. Approve and apply is confirmed with a passkey or password. If the target changes while the request waits, the request goes stale and the assistant must ask again.

Activity and tool reference​

• Activity lists every call with time, client, tool, target and result. Filter by writes, waiting, errors or undone. Some writes can be undone from here. Entries are kept 90 days.
• Tool reference lists every tool with its description, required scope, whether it needs approval, its input schema and the rate limits.

Admin policy​

In Admin › MCP and API, admins decide whether the MCP server and personal tokens are on, whether guests may connect, the rate limits, the maximum token lifetime, whether all MCP clients or only listed ones may connect, and which actions require human approval. Admins can cut any connection in the organization, but they never see its content or token values.

REST API with personal tokens​

The REST API is the same API the web and mobile apps use. It calls the same services as the MCP tools, with the same scopes, space limits, approvals and rate limits.

To create a token:

1. Open My account › MCP and API and select Create token.
2. Enter a name, then pick scopes, spaces and an expiry. Optionally limit it to IP ranges.
3. Copy the token. It is shown only once; after that it can only be revoked and replaced.

Open the REST API page there to download the OpenAPI 3.1 document. Every endpoint is listed with its schema and the scope it needs.

curl -H "Authorization: Bearer $CREWHALL_TOKEN" https://hub.example.com/api/v1/spaces

Rules to know:

• A token acts with its owner's permissions, limited to the chosen scopes and spaces.
• Account, security, session, token management and vault endpoints are never open to tokens. Moving to the trash and share links also need a real session.
• Errors come back as { code, message, details? }. A request outside the token's scopes gets 403 token_scope.
• Lists use cursors: send cursor and limit, and the response is { items, nextCursor }.
• Writing requests accept an Idempotency-Key header, so they are safe to retry.

WebDAV​

A personal token is also the password for mounting Drive as a folder in Finder, Windows Explorer or rclone over WebDAV. See Drive.