Security model

Agentful’s default admin MCP server is an application boundary, not an operations boundary. It authenticates every request, filters tool visibility by permission, and avoids exposing the host.

Request Authentication

MCP requests use bearer tokens:

• Tokens use the shop_mcp_ prefix.
• Plaintext tokens are returned once.
• Token hashes are stored at rest.
• Every MCP request is authenticated independently.
• Missing or invalid tokens receive 401 with WWW-Authenticate.
• Unknown browser Origin values receive 403.

Allowed browser origins can be configured with MCP_ALLOWED_ORIGINS.

Permission Intersection

Effective permissions are the intersection of:

1. The token’s allow-list.
2. The token owner’s current RBAC grants.

This means an existing token is automatically narrowed when the owner loses a role.

Tool Metadata

Agentful tools publish JSON Schema inputs and outputs generated from shared Zod schemas. Tools also mark read-only and destructive operations so MCP clients can present the right affordances and warnings.

No Host Access

Default admin MCP does not include:

Shell

No command runner, package manager access, or arbitrary process execution.

Filesystem

No file browsing or source edits to the API, web app, Docker files, or migrations.

Deployment

No restart, deploy, update, backup, or restore tools in ordinary admin tokens.

Database shell

No raw SQL console exposed to the AI agent. Data changes go through typed tools.

Future Operations Plugin

Deploy, stop, restart, restore, and backup can be added later as a local-only operations plugin. Keep that plugin separate from normal admin MCP:

• Require explicit operator installation.
• Use its own token scope.
• Require confirmations for destructive operations.
• Prefer local-network access only.
• Log every operation and result.
• Never make operations tools visible to ordinary content/catalog agents.