Contract Specification

This page is the normative source of truth for the Tenant Delegated integration contract. The other documentation pages (Endpoints, HMAC Signing, Session Tokens, Login Page) are how-to guides with per-language examples — where they differ from this page, this page wins.

If your connection uses Identity Brokering or Token Exchange, none of this HMAC login/exchange/validate contract applies to you — those models need no auth endpoints on your side. But if their tools call your own API (the common case), that API still receives the forwarded LockMCP token on every call and must verify it independently — see Verifying the forwarded token in your own API.

Versioning

Changes in v2

Version 2 adds the optional, additive toolScopes field to the POST /api/mcp/exchange, POST /api/mcp/validate, and GET /api/mcp/roles responses. The field is backward-compatible: a v1 tenant that omits it remains valid. See Tool scopes.

Endpoint contract

The tenant application MUST expose these six routes at its registered base URL over HTTPS. Two additional optional endpoints MAY be implemented to enable LockMCP to auto-populate the member and role directories.

All HMAC-signed requests use Content-Type: application/json. POST /api/mcp/login uses application/x-www-form-urlencoded.

Request & response schemas

GET /mcp-login

Query parameters appended by the hub:

Returns 200 with an HTML form. If callback_url is not allowlisted or code_challenge_method is not S256, the tenant MUST return an error page and MUST NOT render a usable form.

POST /api/mcp/login

Form fields: email, password, callback_url, state, code_challenge (code_challenge_method and tenant_slug MAY also be present).

• Success: 302 → {callback_url}?state={state}&code={code}
• Failure (bad credentials, disallowed callback_url, malformed code_challenge): 302 → {callback_url}?state={state}&error=access_denied

The tenant MUST validate callback_url against the allowlist before redirecting. If callback_url itself is not allowlisted, the tenant MUST render an error page rather than redirect.

POST /api/mcp/exchange

Request:

{ "code": "<auth code>", "code_verifier": "<PKCE verifier>" }

Success — 200:

{
  "user_id": "user-uuid",
  "email": "user@example.com",
  "session_token": "mcp:<64 hex chars>",
  "expires_in": 3600,
  "roles": ["admin"],
  "display_name": "Jane Doe"
}

Errors:

• 400 missing_fields — code or code_verifier absent
• 401 invalid_code — code unknown, expired, already used, or PKCE verifier mismatch
• 401 — HMAC verification failed (see HMAC)

The auth code MUST be single-use: a successful exchange invalidates it.

POST /api/mcp/validate

Request:

{ "session_token": "mcp:<64 hex chars>" }

Valid — 200:

{ "valid": true, "remaining_seconds": 3542, "roles": ["admin"], "toolScopes": ["createCourse"] }

toolScopes is optional (contract 2+) — same semantics as in exchange. See Tool scopes.

Invalid or expired — 200 (NOT an error status):

{ "valid": false, "remaining_seconds": 0 }

400 missing_fields if session_token is absent.

POST /api/mcp/refresh

Request:

{ "session_token": "mcp:<old token>" }

Success — 200:

{ "session_token": "mcp:<new token>", "expires_in": 3600 }

Error — 401:

{ "error": "session_expired" }

Rotation MUST be atomic: the old token is deleted and the new token created in a single transaction, so the two never coexist. 400 missing_fields if session_token is absent.

POST /api/mcp/logout

Request:

{ "session_token": "mcp:<token>" }

Response — 200:

{ "ok": true }

Logout MUST be idempotent: revoking an unknown or already-revoked token still returns 200 {"ok": true}. 400 missing_fields if session_token is absent.

GET /api/mcp/users

When identityModel = TENANT_DELEGATED, the hub signs the request with the tenant's HMAC key — the same X-Hub-Timestamp, X-Hub-Nonce, and X-Hub-Signature-256 headers as the other server-to-server endpoints, with an empty-string body hash (SHA256("")). For other identity models the request is unauthenticated — protect with IP allowlisting if the data is sensitive.

Response — 200 — top-level array:

[
  { "email": "alice@example.com", "name": "Alice Nguyen" },
  { "email": "bob@example.com", "displayName": "Bob Smith" }
]

Also accepted — object wrapper:

{ "users": [ { "email": "alice@example.com", "name": "Alice Nguyen" } ] }

Fields per user:

Responses with more than 500 entries are ignored. Users already present in LockMCP are skipped (idempotent).

GET /api/mcp/roles

Same transport rules as userListEndpoint — HMAC-signed for TENANT_DELEGATED, unauthenticated for other identity models.

Response — 200 — top-level array:

[
  { "name": "admin",      "description": "Full access to all features",       "toolScopes": ["createCourse", "deleteCourse"] },
  { "name": "instructor", "description": "Can manage courses and students",   "toolScopes": ["createCourse"] },
  { "name": "student",    "description": "Can enrol and view courses",        "toolScopes": [] }
]

Also accepted — object wrapper:

{ "roles": [ { "name": "admin", "description": "Full access" } ] }

Fields per role:

Responses with more than 200 entries are ignored. Roles already present (by slug) are skipped (idempotent).

Tool scopes (v2)

Contract version 2 introduces an optional toolScopes field that lets a tenant declare, per role, exactly which tools a user may invoke. It appears in three responses: POST /api/mcp/exchange, POST /api/mcp/validate (the union of scopes across the user's roles), and GET /api/mcp/roles (the scopes for each individual role).

Enum injection (optional)

Enum injection is an opt-in capability that lets the hub dynamically constrain tool parameter values to the specific resource IDs the current user may access. See the Enum Injection guide for the full how-to.

Bootstrap payload

There is no separate bootstrap endpoint or registered URL to call out to — the payload is embedded directly in responses your server already returns, and the hub stores it on the session record:

{
  "email": "user@example.com",
  "accounts": [
    {
      "accountId": 456,
      "roles": [
        { "role": "LEASING_AGENT", "propertyIds": [101, 102] },
        { "role": "ACCOUNTANT",    "propertyIds": [101] }
      ]
    }
  ]
}

x-mcp-inject OpenAPI marker

Mark any parameter schema in your OpenAPI file that should receive an enum at session time:

schema:
  type: integer
  x-mcp-inject: "propertyIds"   # relay looks up this key in the bootstrap payload

The value must exactly match a key returned in accounts[].roles[] of the bootstrap payload. The marker is stripped before the schema reaches any MCP client — it is a relay-internal directive.

Injection rules

HMAC signing

All four server-to-server endpoints MUST verify an HMAC-SHA256 signature on every request.

Headers

String to sign

{METHOD}\n{FULL_URL}\n{SHA256(body)}\n{timestamp}\n{nonce}

• METHOD — uppercase HTTP method (always POST)
• FULL_URL — the complete request URL as received by the tenant, including query string
• SHA256(body) — lowercase hex-encoded SHA-256 of the raw request body
• timestamp — the X-Hub-Timestamp value, verbatim
• nonce — the X-Hub-Nonce value, verbatim

Rules

Token & code formats

TTLs

The expires_in returned by exchange and refresh MUST equal the tenant's configured session TTL. Auth codes MUST expire no later than their TTL and are additionally consumed on first use.

Configuration

Domain verification

Before activation the tenant MUST prove domain ownership via one of:

• DNS TXT — _mcp-verify.<domain> TXT "mcp-hub-verify=<token>"
• Well-known file — GET https://<base-url>/.well-known/mcp-hub-verification.json returning application/json over HTTPS with no redirect:
  jsonCopy

  { "token": "mcp-hub-verify=<token>" }

Error vocabulary

Conformance

A tenant implementation is conformant when it passes the hub's automated conformance check, run by the hub administrator during onboarding as a gate before the tenant is activated. The check exercises:

1. No-credential checks — bad/missing HMAC → 401; out-of-window timestamp → 401; missing body fields → 400; unknown token to validate → 200 {"valid": false}; non-allowlisted callback_url on /mcp-login → error page; all response shapes match this page.
2. One credentialed happy-path — a tenant-supplied test account drives the full flow: login → exchange → validate → refresh → logout, asserting token format, expires_in, and role resolution.

The same assertions are available to tenant developers as a local self-test to run before handing endpoints to the hub administrator.