Authentication

Every MCP request carries an API key. The gateway authenticates it, builds a request context (your tenant + permission scopes), and filters which tools your agent can see and call.

API key format

Secret keys start with ls_ and are issued from Settings → API Keys in the Vlozi Dashboard. Shown once at creation; stored hashed.

IMPORTANT

MCP uses the same ls_* keys as the REST API. Same key, same scopes, different endpoint.

Sending the key

Either header works:

# Bearer (preferred)
curl -H "Authorization: Bearer ls_xxxxx" https://mcp.vlozi.app/tools
 
# Or x-api-key
curl -H "x-api-key: ls_xxxxx" https://mcp.vlozi.app/tools

Scopes

Each tool has exactly one required permission. The tool list is filtered to what your key can do — agents never see tools they can't call.

Blog

Scope	Tools
`blog:posts.read`	`list_posts`, `get_post`, `search_posts`, `list_tags`, `list_categories`, `get_analytics`
`blog:posts.create`	`create_draft`
`blog:posts.update`	`update_post`
`blog:posts.publish`	`publish_post`, `unpublish_post`, `unschedule_post`
`blog:posts.delete`	`delete_post`

Brain

Scope	Tools
`brain:copilot.use`	`query`, `ingest`, `list_memories`, `get_context`
`brain:memory.delete`	`delete_memory`

Identify your agent

Pass x-agent-id with a stable per-agent string ("claude-desktop", "n8n-publisher", "content-bot"). It shows up in your audit log so you can tell who did what.

curl https://mcp.vlozi.app/tools/blog.list_posts \
  -X POST \
  -H "Authorization: Bearer ls_xxxxx" \
  -H "x-agent-id: claude-desktop" \
  -H "content-type: application/json" \
  -d '{}'

Tenant resolution

You never send a tenant ID — the gateway derives it from your API key. A key belongs to exactly one workspace; cross-tenant access is structurally impossible.

Errors

{ "error": { "code": "...", "message": "..." } }

HTTP	`code`	Cause
401	`invalid_api_key`	Missing, wrong, revoked, or expired key
403	`permission_denied`	Valid key, missing required scope
404	`tool_not_found`	Typo or removed tool
400	`invalid_input`	Input failed validation
400	`service_error`	Upstream product service errored
429	`rate_limited`	See `Retry-After` header

Permission changes propagate within 5 minutes (gateway cache TTL). To force-invalidate, rotate the key.