Authentication & scopes

Every request to the Tiny Command MCP server is authenticated with a workspace API key sent as a bearer token. Each key carries its own permission scopes, so you can hand out a read-only key to an audit bot and a full-access key to your own AI host.

API keys

Keys look like tcm_live_ followed by 32 random bytes (52 characters total). The full secret is shown once, when you generate it; Tiny Command stores only a hash. If you lose it, generate a new one.

Generate, list, and revoke keys in the platform under MCP keys. Issuing keys requires a workspace Admin or Owner role.

How your host authenticates

Your host sends the key on every request:

POST /v1 HTTP/1.1
Host: mcp.tinycommand.com
Authorization: Bearer tcm_live_aB3xK9mPqRv7...
MCP-Protocol-Version: 2025-06-18

The MCP-Protocol-Version header is required on every request after initialization; the host sets it automatically. The server validates the key, resolves your identity and workspace, and runs each tool as you, applying the same per-asset permissions you have in the web app.

Scopes

A key grants only the scopes you select. The MCP server enforces them before any tool runs.

Scope	Lets the key…	Tools
`workspace:read`	inspect the workspace and read data	`list_my_assets`, `describe_my_workspace`, `query_records`, `check_enrichment`
`workspace:build`	generate build previews (but not save them)	`build_system`, `update_asset`
`workspace:write`	save a previewed build	`confirm_save`
`workspace:execute`	operate existing systems (writes, sends, triggers)	`add_record`, `update_record`, `trigger_workflow`, `send_via_integration`, `run_agent`, `run_enrichment`

Issuing and revoking keys is never available over MCP; that always requires the web app.

Presets

The setup wizard offers ready-made bundles so you don't have to reason about individual scopes:

Preset	Scopes	Good for
Standard (recommended)	read + build + write + execute	Your own AI host: full build and operate.
Build-only	read + build + write	Create new systems, but no operating existing data.
Read + operate	read + execute	Drive existing systems without building new ones.
Read-only	read	Inspect-only, perfect for audit bots.
Scout	read + build	Propose builds, but require the web app to save them.
Custom	per-scope checkboxes	Advanced control.

Least privilege

Give each key only what it needs. A monitoring bot should get Read-only; a key you paste into a shared machine should avoid workspace:execute unless it truly needs to send and write.

Revoking a key

Revoke a key any time under MCP keys. Revocation takes effect within 60 seconds (the server caches key validity briefly for performance). After that, every call with the key is rejected.

OAuth 2.1 (forward-compatible)

Workspace API keys are the authentication method today. The server already exposes the OAuth 2.1 discovery surface for hosts that look for it:

GET /.well-known/oauth-protected-resource returns Protected Resource Metadata.
401 responses include WWW-Authenticate: Bearer realm="TinyCommand MCP".

End-user OAuth and Dynamic Client Registration are planned for a future version; no action is needed today.