# API Portal and MCP Gateway setup

Source review: 8 November 2026, sibling `connect-api` checkout. This documents source implementation and recorded local verification; it does not certify a deployed service. No backend files or configurations were changed by this website work.

## API Portal

Open Setup → API Portal → Management in the staff application (the website links to the demo portal, or `VITE_CONNECT_API_DOCS_URL` when configured). Create a client for the integration and select the minimum required scopes. Keep its `cm_live_` key server-side. Send either `Authorization: Bearer cm_live_…` or `X-API-Key: cm_live_…`. Client status, expiry, IP restrictions, feature gates and current organization authorization still apply.

The example base URL is `https://demo.connectme.work/v1/api`; use your environment's URL. Public metadata methods are GET `/v1/api/openapi.json` and GET `/v1/api/mcp-catalog.json`. Local copies ship with this website under `/integration-docs/`. The method reference covers the external integration surface; internal staff, resident and supplier application APIs are not automatically external integration methods.

Each operation declares its own query parameters, required bodies, responses and scopes in [OpenAPI](./openapi.json). Some shared pagination schemas require `skip`, `take`, `sort`, `orderBy` and `filter`, even when a handler only uses a subset. Do not infer supported filtering or offset semantics from field names.

## MCP Gateway

Version 0.3.0 is an independent Node >=24.15.0 service with stateless Streamable HTTP at `/mcp`. Its deployed origin is environment-specific and is not established by this source inspection. It is not necessarily the API origin. An administrator must configure the issuer, resource, backend audience, exchange credentials, exact registered OAuth clients/callbacks, organization allowlist, audience consent URLs and agent `parameters.functions.mcpGateway`. OAuth is disabled by default (`MCP_OAUTH_ENABLED=false`). Keep credentials outside the website bundle.

Use an MCP client with OAuth authorization-code and S256 PKCE support. Discover resource metadata, discover the issuer, authorize using only one audience's scopes, approve in that audience's browser portal, redeem the code and initialize the MCP connection. Use `tools/list` for granted discovery and `tools/call` for execution. No dynamic client registration or client metadata documents are implemented. Exact external-client callback compatibility needs staging evidence.

Codes expire after 60 seconds; access tokens last at most 300 seconds; rotating refresh grants last at most 24 hours. The gateway separately exchanges access tokens for 30-second backend credentials. API keys do not authorize delegated-only methods. Role, feature, tenant, session, property and supplier relationships are revalidated after issuance. Logout, revocation, context changes and refresh replay can invalidate access.

## Supporting HTTP methods

These routes sit outside the external business OpenAPI inventory. The paths are source defaults; use configured origins. OAuth routes are only registered when enabled. `:requestId` is an opaque consent request ID.

| Method | Path | Host / access / behavior |
| --- | --- | --- |
| POST | `/mcp` | Gateway; MCP bearer access token, JSON; stateless protocol requests. Authenticated non-POST requests return 405; JSON batches are rejected. |
| GET | `/catalog.json` | Gateway; public tool catalogue, no execution access |
| GET | `/.well-known/oauth-protected-resource` | Gateway; protected-resource metadata |
| GET | `/.well-known/oauth-protected-resource/mcp` | Gateway; protected-resource metadata |
| GET | `/health` | Gateway; process health; not a full backend check |
| GET | `/ready` | Gateway; checks issuer metadata and capacity; not a full business-operation check |
| GET | `/metrics` | Gateway; Basic gateway credentials; operator metrics |
| GET | `/.well-known/oauth-authorization-server/v1/mcp/oauth` | API; issuer discovery |
| GET | `/v1/mcp/oauth/authorize` | API; validates client, exact callback, resource, state, scope audience and S256 challenge; redirects to consent |
| POST | `/v1/mcp/oauth/token` | API; authorization-code redemption or rotating refresh |
| POST | `/v1/mcp/oauth/revoke` | API; invalidate grant |
| POST | `/v1/mcp/oauth/exchange` | API; gateway-authenticated token exchange; not an end-user integration method |
| GET | `/v1/connect/mcp/consent/:requestId` | API; STAFF preview, current WEB bearer session and organization |
| POST | `/v1/connect/mcp/consent/:requestId` | API; STAFF decision, body `{"approved":true}` or `false` |
| GET | `/v1/connect/client-portal/mcp/consent/:requestId` | API; RESIDENT preview, CLIENT_PORTAL HttpOnly cookie |
| POST | `/v1/connect/client-portal/mcp/consent/:requestId` | API; RESIDENT decision, matching origin and double-submit CSRF |
| GET | `/v1/connect/supplier-portal/mcp/consent/:requestId` | API; SUPPLIER preview, SUPPLIER_PORTAL HttpOnly cookie |
| POST | `/v1/connect/supplier-portal/mcp/consent/:requestId` | API; SUPPLIER decision, matching origin and double-submit CSRF |

Resident/supplier bearer substitution, mixed audiences, native/preview consent and technical-key permission substitution are rejected. Staff work orders currently require OWNER; contractor reads require SUPPLIERS_READ; inspections require enabled current inspection roles/assignments. Resident reads require active property and module access. Supplier reads require explicit active access and both relationship chains.

## Refresh local documentation

Build `connect-api` first using its supported runtime. From this website run `npm run docs:integrations -- ../connect-api`. The script loads the built contract, registers routes without starting a server/database, audits method and scope parity, and copies the generated MCP catalogue. It writes full local JSON contracts, a compact UI index and [all methods](integration-methods.md). Source hashes allow later reconciliation. It does not run in the website build: normal builds work without the sibling checkout. Review [gaps](integration-gaps.md) whenever refreshing the contracts.

Source references: `connect-api/src/routes/v1/api/{routes,mcpReadRoutes}.ts`, `src/plugins/mcpOAuth.ts`, `src/services/mcpOAuth.ts`, `mcp-gateway/src/{server,catalog,tools}.ts`, `mcp-gateway/{AUTHENTICATION,TOOL_CATALOG,DEPLOYMENT}.md` and `docs/mcp-gateway-pilot-verification.md`.