Connect the MCP server

What the server is, and what it is not

The MCP server is a thin layer over /api/v1. It holds no domain knowledge and no database access: every tool calls the REST API. Permission checks, brand scoping and audit logging happen server-side, exactly as they do for a human in the interface.

That leads to the property that matters most: an AI call can never do more than the identity it runs as. If the permission is missing, the operation answers 403, even with a valid token.

Transport is stdio only. The client starts the process itself. There is no daemon, no unit and no HTTP endpoint. The former HTTP transport was removed because it had no caller authentication.

1. Create a dedicated identity

The AI gets its own user, never a personal account. Create it under Settings → Members, activate it and assign exactly the role and brand it needs through a membership. Without a membership every check rejects the token.

2. Issue a token

php bin/console auth:mcp-token mcp@your-company.com
php bin/console auth:mcp-token mcp@your-company.com --ttl 7 --name "Claude Desktop"
php bin/console auth:mcp-token mcp@your-company.com --scope customer.read --scope workitem.list

Without --ttl the token lasts 30 days, 0 means unlimited. The value is shown once; only its hash is stored. You can revoke it at any time via POST /api/v1/api-tokens/{ulid}/revoke.

3. Configure the client

Example for Claude Desktop (claude_desktop_config.json, on macOS in ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "octibiz": {
      "command": "php",
      "args": ["/path/to/octibiz/mcp/bin/server.php"],
      "env": {
        "MCP_API_BASE_URL": "https://your-instance.example",
        "MCP_API_TOKEN": "octi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

That is all. Configuration runs through these two environment variables only: no config file, no secrets in the repository.

4. The three generic tools

Instead of loading hundreds of tool schemas into the client context, there are three that reach every operation:

Tool	Purpose
`list_operations`	Search operations, filtered by area or keyword
`describe_operation`	Describe one operation with its parameters and permissions
`invoke_operation`	Run it

They are fed from the OpenAPI document of the running instance. Generate the catalogue with php bin/console app:mcp:export-operations and refresh it after every API change. If it is missing, the server keeps running and offers only the curated tools.

What ends up in the log

Every write carries the actor type ai and the token identity. Anyone asking later whether a human or an agent acted can see it in the audit log, without someone having had to remember to record it.

Limits

The catalogue deliberately excludes the bootstrap routes: sign-in, public forms and webhook

receivers are not available as tools.

A token without a membership is worthless. That is by design, not an oversight.

mcp.connect · Available from version 0.5.4