MCP integration guide

Overview ¶

The MCP server lives at POST /mcp/board and speaks JSON-RPC 2.0 over HTTP (with SSE for streamed responses). Every call has two identities: the agent (a per-workspace service user authenticated by bearer token) and the actor (the human the agent is acting on behalf of, identified by phone).

Why MCP and not REST

Tools self-describe. The agent fetches the tool catalog at runtime — names, descriptions, JSON schemas, semantics — instead of having a contract hard-coded into JAVIS code. The same server is also reachable from Claude Desktop, Cursor, or any other MCP-capable client without further work.

Quickstart ¶

Provision a token for one workspace and call the smoke-test tool.

1. Provision JAVIS for a workspace

From the admin panel: Admin → Manage Workspaces. On the workspace row, click Provision JAVIS. The page creates the workspace’s service user (if missing), assigns the ws.agent role, rotates the Sanctum token, and shows the plaintext token once in a persistent notification. Copy it immediately.

2. Smoke-test the token

Call whoami-tool first — it’s the cheapest probe and needs only the bearer token. If the token is valid, you’ll get back the agent identity and the workspace it’s bound to.

# Replace TOKEN and BASE_URL with your values. No phone header needed.
curl -s -X POST "$BASE_URL/mcp/board" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "whoami-tool",
      "arguments": {}
    },
    "id": 1
  }'

A successful response contains agent, workspace, and actor: null (since we didn’t send a phone header).

3. Make a real call on behalf of a user

Once whoami-tool works, add X-Acting-User-Phone for any tool that touches workspace data:

# PHONE is the E.164 phone of the human you're acting on behalf of.
curl -s -X POST "$BASE_URL/mcp/board" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Acting-User-Phone: $PHONE" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list-boards-tool",
      "arguments": {}
    },
    "id": 2
  }'

4. Verify the audit row

Every successful or denied call writes a row to agent_call_audit. Inspect it from the admin agent activity feed or directly via SQL:

SELECT id, agent_user_id, actor_user_id, tool, result, error_code, duration_ms, created_at
  FROM agent_call_audit
 ORDER BY id DESC LIMIT 5;

Authentication ¶

Headers

What the server checks, in order

• Sanctum: bearer token resolves to an existing user.
• The token-holding user has is_service = true.
• That user is attached to exactly one workspace via the workspace_members pivot with role = 'agent'. That workspace is the “agent workspace”.
• The acting-user phone resolves to a real user (or, if missing, is auto-created with is_service=false).
• The actor is a member of the agent’s workspace.
• Any board_id / card_id / list_id in the request belongs to that workspace.
• The actor’s role grants the specific permission the tool requires — one verb per operation. Examples: card.create, card.archive, card.complete, card.assign, card.label, card.move, list.create, list.unarchive, label.create, label.delete, custom_field.create, card.custom_field.set, attachment.create, attachment.delete, dependency.add, reminder.cancel, comment.create, comment.edit (own), comment.delete (own), agent.webhook.subscribe, digest.set. The full role × permission matrix lives in database/seeders/RolesAndPermissionsSeeder.php.

If any check fails, the tool returns a JSON-RPC isError: true with a human-readable message and an audit row is written with result = 'denied' and error_code = 'forbidden'.

Roles and the permission matrix

Workspace members are assigned one of five tiered roles via the workspace_members.role pivot. Each role grants a different slice of the verb catalog:

• owner — everything, including workspace.delete and workspace.billing.
• admin — full board/card/list/label/custom-field/webhook management; cannot delete the workspace or touch billing.
• member — day-to-day operational work (create/edit cards, manage checklists/attachments/dependencies, watch, comment). Cannot manage labels, custom-field schemas, member roles, or agent webhooks; cannot bulk-edit, hard-delete cards, or share boards publicly.
• guest — comment only, plus edit/delete their own comments.
• agent — mirrors admin for operational verbs but is further constrained by the per-board agent allowlist (the scope_ok context flag set by BoardTool once the board is confirmed in-workspace). Agents cannot invite, change member roles, delete the workspace, or touch billing.

Tools ¶

All tools are listed here grouped by category. Names use the kebab-case convention Laravel/MCP derives from the class name (CreateCardTool → create-card-tool).

Sanity bearer token only

Returns agent, workspace, and server_time using just the Sanctum token. actor is included only if X-Acting-User-Phone is sent; otherwise it’s null. Use this at boot to verify the token resolves to the correct workspace before issuing any acting-user calls.

Read bearer token only

Read tools are scoped to the agent’s workspace and accept the bearer token alone — X-Acting-User-Phone is optional. If you send it, the audit row records the actor; otherwise the agent itself is recorded.

Board mutations requires board.create / board.update / board.archive

Card mutations requires specific card.* / comment.* verb

Checklists requires checklist.* / checklist_item.*

Reminders requires reminder.cancel

List structural requires list.* permission

Labels requires label.create / .update / .delete

Attachments requires attachment.delete

Card dependencies requires dependency.add / .remove

Custom fields requires custom_field.* / card.custom_field.set

Agent webhooks requires agent.webhook.*

Personal digest requires digest.set

Smart ops utility / card.bulk_edit

Analytics read-only

Workspace membership requires workspace.invite

Worked example: create_card

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create-card-tool",
    "arguments": {
      "board_id": 5,
      "list_id": 10,
      "title": "Reschedule pricing review",
      "due_at": "2026-05-15T10:00:00Z",
      "assignee_phones": ["+62812..."]
    }
  },
  "id": 42
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"card_id\":11,\"title\":\"Reschedule pricing review\",\"list_id\":10,\"position\":\"459769.0000000000\",\"source\":\"agent\",\"created_by_user_id\":42,\"created_via_agent_user_id\":4}"
    }],
    "isError": false
  }
}

Try it ¶

Call any tool live against this server. Provide a workspace JAVIS bearer token and the phone of the human you’re acting on behalf of, fill in the parameters, and send. Each request is real — mutating tools will actually create or change records and write an audit row.

Resources ¶

Resources are read-only data the agent can fetch by URI. Useful for seeding conversation context cheaply, without invoking a tool.

Listing and reading

{ "jsonrpc": "2.0", "method": "resources/templates/list", "params": {}, "id": 1 }

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": { "uri": "board://5/snapshot" },
  "id": 2
}

Errors & audit ¶

Error shapes

• HTTP 401 — bearer missing/invalid. JSON body: {"message":"Unauthenticated."}
• HTTP 404 — X-Acting-User-Phone sent but the phone is not registered and the bearer is not a service token. JSON body: {"message":"Acting user not registered.","error":{"code":"phone_not_linked"}}
• JSON-RPC isError: true — every other failure: missing acting-user (no_actor), bad arguments, no permission, missing record, cross-workspace boundary. The text content carries a human-readable reason.

Audit codes

Audit retention

Rows older than 180 days are pruned daily at 03:30 by php artisan agent:prune-audit. Override via --days=N or test with --dry-run.

Client integration ¶

Any MCP-compatible client works. Below: the official TypeScript SDK pattern, since most agent stacks (including the JAVIS production agent) run in Node.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL(`${BASE_URL}/mcp/board`),
  {
    requestInit: {
      headers: {
        "Authorization": `Bearer ${TOKEN}`,
        "X-Acting-User-Phone": phoneOfTheUserSpeakingNow,
      }
    }
  }
);

const client = new Client({ name: "javis-agent", version: "1.0.0" });
await client.connect(transport);

// One round-trip — server returns full tool list with JSON schemas.
const { tools } = await client.listTools();

const result = await client.callTool({
  name: "create-card-tool",
  arguments: { board_id: 5, list_id: 10, title: "From Javis" }
});

Data model side-effects ¶

What changes in the database when JAVIS acts.

Cards created via the agent

• cards.source = 'agent'
• cards.created_by_user_id = the human (the actor)
• cards.created_via_agent_user_id = the workspace JAVIS service user
• UI surfaces this as the “via JAVIS” badge on the card.

Events fired

Tools dispatch the same events the web UI does — CardCreated, CardUpdated, CardMoved, CardArchived, CommentAdded, ListCreated, ListMoved, ListArchived, ListUpdated. Broadcast subscribers (Reverb) and notification dispatchers see no difference between web-originated and agent-originated changes, beyond the source field.

Notifications

Assignments and due-date changes schedule the same NotificationDispatch rows that the REST API path writes. The actor is recorded on the card.assignees pivot and as the actor_id in the assignment notification payload.

Ops & troubleshooting ¶

Rotating a token

Admin → Manage Workspaces → Provision JAVIS on the affected workspace. The previous token is deleted; the new plaintext is shown once. Live agent processes need to be restarted with the new token.

Disabling JAVIS for a workspace

Delete the JAVIS user’s tokens ($javis->tokens()->delete()) — every subsequent MCP call returns 401, but no kanban data is affected. The user row and audit history remain.

Pagination on tools/list

Default page size is 10 tools. The response includes nextCursor when there are more. JAVIS’s production client should walk the cursor; ad-hoc curl callers can pass ?per_page=50 to get them all in one shot.

Local debugging

Run php artisan mcp:inspector to open the Laravel/MCP web inspector against your local server. Useful for poking at tool schemas without writing a client.

Appendix · file map ¶

Where to look in the codebase, in execution order.