Skip to main content

Managed credentials

Create a dedicated principal with studio.mcp.use, membership in the required workspaces and the permissions for its tools. Use a different connection ID for each independent client. Generate the secret locally.
Store the token in the client’s secret store and only its hash in the Laravel environment. Set an explicit expiry as a Unix timestamp in seconds.
In this example the second workspace is read-only for this credential. Studio accepts only explicitly named tools. An empty list grants none. * has no special meaning. A global list further narrows connection grants. A workspace_tools entry can only remove tools from that workspace. A null workspace list means all workspaces accessible to the principal, subject to global config and tenant policy. Workspace creation is a tenant-level operation requiring its own grant. The connection ID begins with a lowercase letter and may contain lowercase letters, digits, underscores and hyphens (up to 64 characters). Its token secret is 64 lowercase hexadecimal characters. principal_type is the application’s registered Studio model alias. principal_id is a string identifier, including when the underlying database key is numeric.

Tenant isolation

For a non-tenant installation, explicitly set tenant_key => null. In a tenant installation use the corresponding TenantIdentity::key(). Configure trusted connection_middleware to establish the tenant before Studio authorizes the managed principal. Keep tenant resolution available for both the MCP endpoint and its HTTP transfer paths. The resolved tenant must match the credential and the workspace. See tenancy.

Host-authenticated mode

With authentication => 'bearer', Studio relies on applications’ configured middleware and principal. The default is middleware => ['auth:sanctum']. Only the four browse/read tools are offered in this mode. Its global workspace and tool allowlists still apply. The local standalone demo may use a session middleware configuration. The managed mode is required for mutation and binary-transfer tools.

Rotate or revoke

Replace token_hash and expiry under the existing ID to rotate without changing the connection’s upload ownership scope. The principal and tenant must also stay the same to resume those sessions. A different connection ID cannot resume the former client’s uploads. Disable with enabled => false or remove the connection. Reload cached configuration and long-lived workers on all application instances when rotating or revoking a grant. Revocation stops further MCP calls and authenticated transfers once applied. Already-issued S3 part URLs remain usable until their signature expires. They cannot complete an upload by themselves.

Origin, rate limits and logs

  • Serve the MCP endpoint and transfers over HTTPS. Clients send the bearer token in the Authorization header. Proxy and client logs should redact credentials, signed URLs and file content.
  • If the request has an Origin header, it must match an allowed origin exactly. With origins => null, Studio uses the application URL without a trailing slash. Requests without Origin are accepted through the same authentication chain.
  • requests_per_minute defaults to 60 and is clamped to 1–600 for the Laravel throttle middleware. Both RPC calls and authenticated transfer routes pass through the middleware.
  • Studio logs managed mutation outcomes with tool, connection, principal and workspace identifiers when available. Transfer audit entries identify the uploaded entry. Configure retention and access to application logs.
  • MCP web responses use private, no-store caching. See the troubleshooting checklist when using a reverse proxy.