MCP authentication
Bearer tokens, validation, and relationship to the REST API tsid.
Every MCP request (except the health check) must include an Authorization header:
Authorization: Bearer YOUR_TOKEN_30_CHARS
Token format
- Length: 30 characters total
- Structure: 10-character token ID + 20-character bcrypt hash segment
- Storage: table
cd_psidin the Velip SaaS database - Same format as REST API
tsidtokens — issued and managed from your Velip account portal - MCP tokens are MCP-only: a token created for the MCP Server (manual MCP token or OAuth connector) is refused by the REST API v2 when called directly (error
114, Token not allowed for REST API). For direct HTTP calls, create a regular API token.
To obtain a token, contact your Velip account administrator or use the token management UI in the Velip control panel.
What the server validates
On each request the MCP server:
- Parses the Bearer token from the
Authorizationheader - Looks up
cd_psid— token must exist and be active - Resolves the customer (
cdcs_id) and user context - Checks IP allowlist (same rules as REST authentication)
- Loads MCP permissions from
cdpsid_mcp_apis - Forwards the same token to the Velip PHP API when executing a tool
Error responses
| HTTP | Meaning |
|---|---|
401 |
Missing, invalid, or expired token |
403 |
Token valid but MCP disabled globally, channel not enabled, or IP blocked |
Example:
{
"success": false,
"error": "Não autenticado",
"status_code": 401
}
Rate limiting
Failed authentication attempts share the same brute-force and blacklist policies as the REST API. See REST authentication and rate limits.
Security tips
- Store tokens in environment variables or a secret manager — never commit them to git.
- Enable the IP allowlist on your account when using MCP from fixed server IPs.
- Rotate tokens immediately if you suspect a leak.
- Grant only the MCP channels you need (Permissions).
Next
- Permissions — configure
cdpsid_mcp_apis - Getting started — first authenticated call