MCP server

From externa-core 1.4.0 (#121), Externa ships an optional first-party Model Context Protocol server at /mcp (streamable HTTP, laravel/mcp). AI clients such as Claude Code, Cursor, or VS Code can read collections, items, and files, and propose writes, with the same permissions as the in-app assistant. It is off by default.

Enable

AI_MCP_ENABLED=true
AI_MCP_WRITE_ENABLED=false
AI_MCP_RATE_LIMIT_PER_MINUTE=60

Run php artisan optimize:clear (or externa:upgrade) after changing these keys when config is cached. The endpoint is CSRF-exempt (mcp, mcp/* in bootstrap/app.php).

Authentication

Clients authenticate with an owned API key sent as a Bearer token. OAuth / Passport is not wired yet.

POST /mcp
Authorization: Bearer ek_YOUR_SECRET

AuthenticateMcpRequestMiddleware rejects the request when:

After these checks the request runs as the key owner, with the key's role and scopes as an extra ceiling. Each call updates the key's last_used_at.

API key scopes and owners

API keys gain two fields in 1.4.0:

Create or edit keys under Settings → API Keys (/settings/api-keys); the form picks the owner and the scopes. Keys are revoked automatically when their owner is deactivated or deleted. The upgrade backfills owners for existing keys — see Upgrade — 1.3.x → 1.4.0.

Write tools need all of: AI_MCP_WRITE_ENABLED=true, the mcp:write scope, and a key that is not read_only. Otherwise they are hidden from tools/list and refuse calls.

Tools

Tools are thin adapters over the shared AI tool registry (app/Mcp/Tools/*), so they run the same permission checks as the in-app assistant and write the same audit trail (surface=mcp).

Read tools

Write tools

Listed only when the write gate above allows it. There are no delete tools.

Write tools go through AiToolExecutorService, which also requires the AI write gate: AI_WRITE_TOOLS=true and the tool class (ManageCollectionItems or ManageFiles) on the write allowlist. Every mutating MCP call is then parked for human approval (pending_approval) instead of running. See AI tool approvals & audit.

publish_item also applies the collection update permission, the role's item filter, and the versioning checks of the admin publish action. Publishing through MCP only fires deploy hooks (Project settings) after the call has been approved (#435).

Resources

Authorization

From #435, every MCP tool and resource enforces the same rules as the chat tools:

• collection, item, and field permissions (including the role's item filter and field-level read rules);
• file ACL and read_private;
• the API key's collection_slugs, files_scope, and read_only.

A key scoped to collection_slugs=[blog] cannot read other collections over MCP, and a key with files_scope=none cannot read files. Prompt-injection and denied-permission cases for chat and MCP are covered by the Pest suite under tests/Feature/Ai/Security/* (#204).

Client setup

Any MCP client that supports streamable HTTP with a custom header works. Examples (replace the host and key):

# Claude Code
claude mcp add --header "Authorization: Bearer ek_YOUR_SECRET" \
  --transport http externa https://cms.example.com/mcp

{
  "mcpServers": {
    "externa": {
      "url": "https://cms.example.com/mcp",
      "headers": { "Authorization": "Bearer ek_YOUR_SECRET" }
    }
  }
}

Source map