Connect MCP

Agentful’s admin surface is the MCP server at POST /api/mcp. The transport is Streamable HTTP in stateless JSON mode. Any MCP client that supports HTTP transport and custom headers can connect.

Mint A Token

From a logged-in admin session, mint a token with only the permissions the agent needs:

POST /api/mcp/tokens
Content-Type: application/json

{
  "name": "claude-code-local",
  "permissions": ["products:read", "products:manage", "settings:read"]
}

The plaintext token is returned once. Store it in the MCP client configuration or a local secret manager, not in the repo.

Claude Code

claude mcp add --transport http agentful-admin http://localhost:7300/api/mcp \
  --header "Authorization: Bearer shop_mcp_..."

For a hosted shop, replace the URL with the hosted API origin:

claude mcp add --transport http agentful-admin https://<shop>.agentful.app/api/mcp \
  --header "Authorization: Bearer shop_mcp_..."

Token Permissions

Tool visibility is computed on every request:

1. The bearer token must be valid and unrevoked.
2. The token’s stored allow-list must include the permission.
3. The token owner must still have the live RBAC grant.

If an owner loses a role, existing tokens lose those effective permissions immediately.

Safe Prompting

Give the agent the desired business change and require it to use MCP tools:

Use the Agentful MCP server only. Do not edit source files.
Make the footer brand link to https://premierstudio.ai.

The agent should call:

{
  "tool": "settings.update",
  "arguments": {
    "content": {
      "footerBrandUrl": "https://premierstudio.ai"
    }
  }
}

That is a persisted settings write, not a patch to the web app.

What MCP Does Not Include

Default admin MCP tokens do not expose:

• Shell commands.
• Docker or compose.
• Filesystem reads or writes.
• Source code edits.
• Database backup or restore.
• Deploy, restart, or update operations.

Those capabilities belong in a future local-only operations plugin with a separate token and explicit operator approval.