Endpoints

Your tenant app must implement 5 API endpoints. The hub calls these endpoints server-to-server (except the login page, which the user's browser visits). Two additional optional endpoints (GET /api/mcp/users and GET /api/mcp/roles) can be implemented to enable LockMCP to auto-populate the member and role directories.

Applies to Tenant Delegated connections only. Identity Brokering and Token Exchange connections don't require you to host any endpoints.

This is a how-to guide. The Contract Specification is the normative reference for request/response schemas and status codes.

Endpoint	HMAC signed?	Purpose
`POST /api/mcp/login`	No	Form POST from login page — issues auth code
`POST /api/mcp/exchange`	Yes	Exchange auth code + PKCE verifier for session token
`POST /api/mcp/validate`	Yes	Validate a session token, return TTL + roles
`POST /api/mcp/refresh`	Yes	Rotate session token atomically
`POST /api/mcp/logout`	Yes	Revoke a session token
`GET /api/mcp/users`	TENANT_DELEGATED only	Optional. Return list of tenant users
`GET /api/mcp/roles`	TENANT_DELEGATED only	Optional. Return list of tenant roles

POST /api/mcp/login

Handles the form POST from the login page. Authenticates the user, issues a short-lived auth code, and redirects back to the hub's callback URL with the code.

HMAC: Not required (this is a browser form submission, not a server-to-server call).

Request: application/x-www-form-urlencoded (form data)

Field	Description
`email`	User's email address
`password`	User's password
`callback_url`	Hub callback URL (must be in allowlist)
`state`	Opaque state string — pass back unchanged
`code_challenge`	PKCE S256 challenge (43-char base64url)

Success: 302 redirect to {callback_url}?state={state}&code={code}

Failure: 302 redirect to {callback_url}?state={state}&error=access_denied

javascript

// app/api/mcp/login/route.ts
import { NextRequest, NextResponse } from "next/server";
import { auth } from "@/lib/auth";
import { issueAuthCode } from "@/lib/mcp-contract/auth-code-store";
import { isAllowedCallbackUrl } from "@/lib/mcp-contract/config";

// PKCE S256 challenge is always 43 chars of base64url
const CODE_CHALLENGE_RE = /^[A-Za-z0-9_-]{43}$/;

export async function POST(request: NextRequest) {
  const formData = await request.formData();

  const email = formData.get("email") as string | null;
  const password = formData.get("password") as string | null;
  const callbackUrl = formData.get("callback_url") as string | null;
  const state = formData.get("state") as string | null;
  const codeChallenge = formData.get("code_challenge") as string | null;

  if (!email || !password || !callbackUrl || !state || !codeChallenge) {
    return NextResponse.json(
      { error: "Missing required fields" }, { status: 400 });
  }

  // Open-redirect defense
  if (!isAllowedCallbackUrl(callbackUrl)) {
    return NextResponse.json(
      { error: "callback_url host not allowed" }, { status: 400 });
  }

  // PKCE S256 format check
  if (!CODE_CHALLENGE_RE.test(codeChallenge)) {
    return NextResponse.json(
      { error: "Invalid code_challenge: must be 43-char base64url (S256)" },
      { status: 400 });
  }

  let userId: string;
  try {
    const result = await auth.api.signInEmail({
      body: { email, password },
    });
    if (!result?.user) throw new Error("Auth returned no user");
    userId = result.user.id;
  } catch {
    // Auth failed — redirect with error
    const errorUrl = new URL(callbackUrl);
    errorUrl.searchParams.set("state", state);
    errorUrl.searchParams.set("error", "access_denied");
    return NextResponse.redirect(errorUrl.toString(), { status: 302 });
  }

  // Issue auth code and redirect back to hub
  const code = issueAuthCode(userId, codeChallenge);
  const successUrl = new URL(callbackUrl);
  successUrl.searchParams.set("state", state);
  successUrl.searchParams.set("code", code);
  return NextResponse.redirect(successUrl.toString(), { status: 302 });
}

POST /api/mcp/exchange

Exchanges an auth code (from the login flow) and a PKCE code verifier for a session token.

Request headers: HMAC signature headers (X-Hub-Timestamp, X-Hub-Nonce, X-Hub-Signature-256)

Request body:

json

{
  "code": "base64url-encoded-auth-code",
  "code_verifier": "original-PKCE-verifier-string"
}

Success response (200):

json

{
  "user_id": "user-uuid",
  "email": "user@example.com",
  "session_token": "mcp:a1b2c3d4...",
  "expires_in": 3600,
  "roles": ["admin"],
  "display_name": "Jane Doe",
  "enum_scopes": {
    "email": "user@example.com",
    "accounts": [
      {
        "accountId": 456,
        "roles": [
          { "role": "LEASING_AGENT", "propertyIds": [101, 102] }
        ]
      }
    ]
  }
}

enum_scopes is optional — include it to enable enum injection. The hub stores this payload on the session record and uses it to inject enum constraints into tool parameters marked with x-mcp-inject. The key names inside each role entry (e.g. propertyIds) must match the x-mcp-inject values in your OpenAPI spec. Omit enum_scopes entirely if your tenant doesn't use enum injection.

getUserEnumScopes (shown in the examples below) is a placeholder for your own data layer — implement it to query your database for the user's accounts and roles. See Enum Injection for the expected payload shape.

Error responses:

401 — invalid/expired code, PKCE mismatch, HMAC failure
400 — missing code or code_verifier

javascript

// app/api/mcp/exchange/route.ts
import { NextRequest, NextResponse } from "next/server";
import { verifyHubSignature } from "@/lib/mcp-contract/hmac";
import { consumeAuthCode } from "@/lib/mcp-contract/auth-code-store";
import { createMcpSession } from "@/lib/mcp-contract/session-token";
import { getUserRolesForMcp } from "@/lib/mcp-contract/role-mapping";
import { getUserEnumScopes } from "@/lib/mcp-contract/enum-scopes"; // optional — your own implementation
import { prisma } from "@/lib/prisma";

const SESSION_TTL_SEC = parseInt(
  process.env.MCP_CONTRACT_SESSION_TTL_SEC ?? "3600", 10);

export async function POST(request: NextRequest) {
  const rawBody = await request.text();

  const hmacResult = await verifyHubSignature(
    "POST", request.url, rawBody, request.headers);
  if (!hmacResult.ok) {
    return NextResponse.json(
      { error: hmacResult.error }, { status: hmacResult.status });
  }

  let body: { code?: string; code_verifier?: string };
  try { body = JSON.parse(rawBody); }
  catch { return NextResponse.json(
    { error: "Invalid JSON" }, { status: 400 }); }

  const { code, code_verifier } = body;
  if (!code || !code_verifier) {
    return NextResponse.json(
      { error: "Missing code or code_verifier" }, { status: 400 });
  }

  const record = consumeAuthCode(code, code_verifier);
  if (!record) {
    return NextResponse.json(
      { error: "invalid_code" }, { status: 401 });
  }

  const user = await prisma.user.findUnique({
    where: { id: record.userId },
  });
  if (!user) {
    return NextResponse.json(
      { error: "user_not_found" }, { status: 401 });
  }

  const [{ token, expiresIn }, roles, enumScopes] = await Promise.all([
    createMcpSession(user.id, SESSION_TTL_SEC),
    getUserRolesForMcp(user.id),
    getUserEnumScopes(user.id), // returns null if not using enum injection
  ]);

  return NextResponse.json({
    user_id: user.id,
    email: user.email,
    session_token: token,
    expires_in: expiresIn,
    roles,
    display_name: user.name,
    ...(enumScopes && { enum_scopes: enumScopes }),
  });
}

POST /api/mcp/validate

Validates a session token and returns whether it's valid, the remaining TTL, and the user's roles.

Request body:

json

{ "session_token": "mcp:a1b2c3d4..." }

Response (200) — valid token:

json

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

Response (200) — expired/invalid token:

json

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

javascript

// app/api/mcp/validate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { verifyHubSignature } from "@/lib/mcp-contract/hmac";
import { findMcpSession } from "@/lib/mcp-contract/session-token";
import { getUserRolesForMcp } from "@/lib/mcp-contract/role-mapping";
import { prisma } from "@/lib/prisma";

export async function POST(request: NextRequest) {
  const rawBody = await request.text();

  const hmacResult = await verifyHubSignature(
    "POST", request.url, rawBody, request.headers);
  if (!hmacResult.ok) {
    return NextResponse.json(
      { error: hmacResult.error }, { status: hmacResult.status });
  }

  let body: { session_token?: string };
  try { body = JSON.parse(rawBody); }
  catch { return NextResponse.json(
    { error: "Invalid JSON" }, { status: 400 }); }

  const { session_token } = body;
  if (!session_token) {
    return NextResponse.json(
      { error: "Missing session_token" }, { status: 400 });
  }

  const session = await findMcpSession(session_token);
  if (!session) {
    return NextResponse.json(
      { valid: false, remaining_seconds: 0 });
  }

  // Verify user still exists
  const user = await prisma.user.findUnique({
    where: { id: session.userId },
    select: { id: true },
  });
  if (!user) {
    return NextResponse.json(
      { valid: false, remaining_seconds: 0 });
  }

  const remainingMs = session.expiresAt.getTime() - Date.now();
  const remainingSeconds = Math.floor(remainingMs / 1000);
  const roles = await getUserRolesForMcp(session.userId);

  return NextResponse.json({
    valid: true, remaining_seconds: remainingSeconds, roles,
  });
}

POST /api/mcp/refresh

Rotates a session token atomically: deletes the old token and creates a new one in a single transaction.

Request body:

json

{ "session_token": "mcp:old-token..." }

Success response (200):

json

{ "session_token": "mcp:new-token...", "expires_in": 3600 }

Error response (401):

json

{ "error": "session_expired" }

javascript

// app/api/mcp/refresh/route.ts
import { NextRequest, NextResponse } from "next/server";
import { verifyHubSignature } from "@/lib/mcp-contract/hmac";
import { refreshMcpSession } from "@/lib/mcp-contract/session-token";

const SESSION_TTL_SEC = parseInt(
  process.env.MCP_CONTRACT_SESSION_TTL_SEC ?? "3600", 10);

export async function POST(request: NextRequest) {
  const rawBody = await request.text();

  const hmacResult = await verifyHubSignature(
    "POST", request.url, rawBody, request.headers);
  if (!hmacResult.ok) {
    return NextResponse.json(
      { error: hmacResult.error }, { status: hmacResult.status });
  }

  let body: { session_token?: string };
  try { body = JSON.parse(rawBody); }
  catch { return NextResponse.json(
    { error: "Invalid JSON" }, { status: 400 }); }

  const { session_token } = body;
  if (!session_token) {
    return NextResponse.json(
      { error: "Missing session_token" }, { status: 400 });
  }

  const result = await refreshMcpSession(
    session_token, SESSION_TTL_SEC);
  if (!result) {
    return NextResponse.json(
      { error: "session_expired" }, { status: 401 });
  }

  return NextResponse.json({
    session_token: result.token,
    expires_in: result.expiresIn,
  });
}

POST /api/mcp/logout

Revokes a session token (deletes it from storage).

Request body:

json

{ "session_token": "mcp:token-to-revoke..." }

Response (200):

json

{ "ok": true }

javascript

// app/api/mcp/logout/route.ts
import { NextRequest, NextResponse } from "next/server";
import { verifyHubSignature } from "@/lib/mcp-contract/hmac";
import { revokeMcpSession } from "@/lib/mcp-contract/session-token";

export async function POST(request: NextRequest) {
  const rawBody = await request.text();

  const hmacResult = await verifyHubSignature(
    "POST", request.url, rawBody, request.headers);
  if (!hmacResult.ok) {
    return NextResponse.json(
      { error: hmacResult.error }, { status: hmacResult.status });
  }

  let body: { session_token?: string };
  try { body = JSON.parse(rawBody); }
  catch { return NextResponse.json(
    { error: "Invalid JSON" }, { status: 400 }); }

  const { session_token } = body;
  if (!session_token) {
    return NextResponse.json(
      { error: "Missing session_token" }, { status: 400 });
  }

  await revokeMcpSession(session_token);
  return NextResponse.json({ ok: true });
}

GET /api/mcp/users

Returns the list of active users in the tenant application. LockMCP calls this endpoint when a connection with a configured userListEndpoint path is created or updated. Synced users appear in the Members tab with source badge Auto and are assigned the tenant's default role.

HMAC: Signed when identity model is TENANT_DELEGATED (same headers as other server-to-server endpoints, empty-string body hash). Unauthenticated for other identity models — protect with IP allowlisting if needed.

Response (200):

json

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

Top-level array or { "users": [...] } wrapper both accepted. Each entry requires an email field; name / displayName is optional.

javascript

// app/api/users/route.ts
// Configure this path as userListEndpoint on the LockMCP connection
import { NextResponse } from "next/server";
import { prisma } from "@/lib/prisma";

export async function GET() {
  const users = await prisma.user.findMany({
    where: { isActive: true },
    select: { email: true, name: true },
    orderBy: { name: "asc" },
  });

  return NextResponse.json(
    users.map((u) => ({ email: u.email, name: u.name ?? u.email }))
  );
}

GET /api/mcp/roles

Returns the list of roles defined in the tenant application. LockMCP calls this endpoint when a connection with a configured roleListEndpoint path is created or updated. Synced roles appear in the Roles tab and can be assigned to members or used for tool access control.

HMAC: Signed when identity model is TENANT_DELEGATED. Unauthenticated for other identity models — protect with IP allowlisting if needed.

Response (200):

json

[
  { "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": [] }
]

Top-level array or { "roles": [...] } wrapper both accepted. Each entry requires a name field; description and toolScopes are optional. toolScopes (contract 2+) lists the OpenAPI operationIds each role may invoke — see the Contract Specification.

javascript

// app/api/roles/route.ts
// Configure this path as roleListEndpoint on the LockMCP connection
import { NextResponse } from "next/server";

// Define your tenant's roles here (or load from DB)
const TENANT_ROLES = [
  { 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: [] },
];

export async function GET() {
  return NextResponse.json(TENANT_ROLES);
}

Router registration (JavaScript)

Wire the raw-body middleware once, then mount all MCP routers:

javascript

// app.js
const express = require("express");
const app = express();

// Capture raw body as string before any JSON parsing — required for HMAC verification
app.use(express.raw({ type: "*/*" }), (req, _res, next) => {
  req.rawBody = req.body ? req.body.toString() : "";
  next();
});

// Parse JSON and form bodies for route handlers (after raw body is captured)
app.use(express.json());
app.use(express.urlencoded({ extended: false }));

app.use(require("./routes/mcp-login"));
app.use(require("./routes/mcp-exchange"));
app.use(require("./routes/mcp-validate"));
app.use(require("./routes/mcp-refresh"));
app.use(require("./routes/mcp-logout"));
app.use(require("./routes/mcp-users"));
app.use(require("./routes/mcp-roles"));

app.listen(3000);

Router registration (Python)

Register all MCP routers in your FastAPI app. The dependencies on each HMAC-protected route handle verification automatically.

python

# main.py
from fastapi import FastAPI
from routers import (
    mcp_login, mcp_exchange, mcp_validate, mcp_refresh, mcp_logout,
    mcp_users, mcp_roles,
)

app = FastAPI()
app.include_router(mcp_login.router)
app.include_router(mcp_exchange.router)
app.include_router(mcp_validate.router)
app.include_router(mcp_refresh.router)
app.include_router(mcp_logout.router)
app.include_router(mcp_users.router)
app.include_router(mcp_roles.router)

Filter registration (Java)

java

// FilterConfig.java
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<HmacVerificationFilter> hmacFilter() {
        var reg = new FilterRegistrationBean<>(
            new HmacVerificationFilter());
        reg.addUrlPatterns(
            "/api/mcp/exchange",
            "/api/mcp/validate",
            "/api/mcp/refresh",
            "/api/mcp/logout",
            "/api/mcp/users",
            "/api/mcp/roles"
        );
        reg.setOrder(1);
        return reg;
    }
}