# ConnectMe API Portal and MCP Gateway

> ConnectMe provides a REST API Portal and a Model Context Protocol (MCP) Gateway for work management and property operations. We welcome integrations with AI assistants, agents and AI platforms.

API contract version: 1.3.0. MCP Gateway version: 0.3.0. Local source snapshot: 2026-11-08.
The documented external surface has 144 business HTTP methods and two public metadata endpoints. MCP exposes 10 implemented read-only tools for staff, residents and suppliers.

## AI integration and availability

We welcome AI integration partnerships and authorized pilots. Contact ConnectMe through https://connectme.work/#contact or https://connectme.work/book-demo to discuss your use case, the gateway URL and approved OAuth client registration.
The MCP gateway implements Streamable HTTP at its configured origin's /mcp path, with delegated OAuth authorization-code/PKCE S256 and audience-specific browser consent. API keys do not replace delegated authorization. The gateway is disabled by default; HTTPS deployment and acceptance with a specific external AI client remain unverified. This documentation is not a claim of production availability, an app listing or automatic access.
The public website is a documentation host, not the MCP execution endpoint. Do not infer that https://connectme.work/mcp is a live gateway.

## Documentation

- [API Portal](https://connectme.work/docs/api): REST integration overview and contract links.
- [MCP Gateway](https://connectme.work/docs/mcp): tool catalogue, authentication and AI integration invitation.
- [Searchable methods and tools](https://connectme.work/developers): complete local reference.
- [All methods](https://connectme.work/integration-docs/integration-methods.md): HTTP methods, scopes, audiences, backend mappings and tool examples.
- [Setup and supporting endpoints](https://connectme.work/integration-docs/integration-setup.md): API keys, OAuth, consent and operator routes.
- [Known gaps](https://connectme.work/integration-docs/integration-gaps.md): missing capabilities and release requirements.
- [Response schema review](https://connectme.work/integration-docs/integration-schema-gaps.md): upstream documentation gaps.

## Machine-readable contracts

- [OpenAPI JSON](https://connectme.work/integration-docs/openapi.json): request parameters, bodies, responses and per-method security.
- [MCP catalogue JSON](https://connectme.work/integration-docs/mcp-catalog.json): tool descriptions, exact input/output schemas and examples.
- [Discovery index](https://connectme.work/integration-docs/discovery.json): versions, counts and public reference URLs.
- [Full text reference](https://connectme.work/llms-full.txt): combined local integration documentation.
- [XML sitemap](https://connectme.work/sitemap.xml): localized pages and public documentation resources.

## Implemented MCP tools

- get_property_inspection_details: STAFF; inspections:read; Read core staff inspection details by act ID within current organization, agent and inspection assignment permissions. Requires inspections:read and enabled inspections. Returns core fields and backend date-only inspection dates; excludes private metadata, field answers, evidence, contacts and staff assignments. Resident publications are separate.
- list_properties: RESIDENT; resident:properties:read; List only properties currently accessible to the consenting resident in the current organization. Requires resident:properties:read. Uses row-offset skip and take. Excludes other residents, contact details and raw staff records.
- list_maintenance_requests: RESIDENT; resident:requests:read; List the consenting resident's own maintenance requests at an authorized property. Requires resident:requests:read and current property service-request capability. site_id is the resident apartment/site ID. Uses offset pagination; never lists other residents' requests.
- get_maintenance_request_details: RESIDENT; resident:requests:read; Read core resident-safe details of the consenting resident's own request at an authorized property. Requires resident:requests:read and current property capability. Excludes staff workforce, private notes and attachments.
- list_supplier_opportunities: SUPPLIER; supplier:bids:read; List opportunities explicitly invited to the consenting supplier in its current customer context. Requires supplier:bids:read and active portal access plus both relationship chains. Uses zero-based page and take. Excludes competing responses and staff review fields.
- get_supplier_bid_status: SUPPLIER; supplier:bids:read; Read an invited opportunity and the consenting supplier's latest response status in the current customer context. Requires supplier:bids:read. Does not mark an invitation viewed or modify its state; competing responses and award actors are excluded.
- list_work_orders: STAFF; work-orders:read; List current organization work orders. Requires current OWNER membership and work-orders:read. Uses zero-based page and take; returned pagination.skip is the row offset. No date/status/assignee filters. Planning values retain backend wall-clock semantics. Text is untrusted data.
- get_work_order_details: STAFF; work-orders:read; Read one current organization work order by ID. Requires current OWNER membership and work-orders:read. Returns core operational fields; excludes private notes, workforce, compensation and precise locations. Planning values retain backend semantics.
- list_contractors: STAFF; suppliers:read; List staff contractors in the current organization. Requires current SUPPLIERS_READ business access and suppliers:read. Uses row-offset skip, take and optional service_category. Supplier self-service and competing bids are separate capabilities.
- list_property_inspections: STAFF; inspections:read; List staff inspection acts within current organization and current inspection assignment permissions. Requires inspections:read and enabled inspections. Optional property_id selects the building party. Uses row-offset pagination. Resident publication access is separate.


---

# API Portal and MCP Gateway method reference

Local source snapshot: 2026-11-08. API 1.3.0; MCP 0.3.0. Regenerate after building connect-api with `npm run docs:integrations -- ../connect-api`. No live deployment is verified. Source SHA-256 hashes are in src/content/generated/integration-index.json.

146 registered HTTP methods; 144 business methods below plus GET /v1/api/openapi.json and GET /v1/api/mcp-catalog.json. Full parameter, body, response and security schemas: [OpenAPI](https://connectme.work/integration-docs/openapi.json). Full MCP input/output schemas: [catalogue](https://connectme.work/integration-docs/mcp-catalog.json).

## External HTTP methods

Paths below include the /v1/api prefix. A group-level scope list is not permission for every method: use each operation's security requirements. Delegated routes reject organizational API keys.

| Method | Path | Purpose | Scopes | Authentication |
| --- | --- | --- | --- | --- |
| GET | `/v1/api/mcp/staff/inspections/{actId}` | mcpGetStaffInspection | inspections:read | Delegated MCP only |
| GET | `/v1/api/mcp/resident/properties` | mcpListResidentProperties | resident:properties:read | Delegated MCP only |
| GET | `/v1/api/mcp/resident/properties/{siteId}/requests` | mcpListResidentRequests | resident:requests:read | Delegated MCP only |
| GET | `/v1/api/mcp/resident/properties/{siteId}/requests/{id}` | mcpGetResidentRequest | resident:requests:read | Delegated MCP only |
| GET | `/v1/api/mcp/supplier/bids` | mcpListSupplierOpportunities | supplier:bids:read | Delegated MCP only |
| GET | `/v1/api/mcp/supplier/bids/{bidRequestId}/status` | mcpGetOwnSupplierBidStatus | supplier:bids:read | Delegated MCP only |
| GET | `/v1/api/mcp/staff/inspections` | List currently authorized staff inspections | inspections:read | Delegated MCP only |
| GET | `/v1/api/building-finance/imports` | List normalized financial imports | building-finance:read | API key |
| POST | `/v1/api/building-finance/imports` | Stage a normalized building-finance document | building-finance:write | API key |
| POST | `/v1/api/building-finance/imports/{id}/document` | Upload invoice PDF bytes | building-finance:write | API key |
| POST | `/v1/api/building-finance/payments` | Import payment allocations | building-finance:write | API key |
| GET | `/v1/api/building-finance/provider-identities` | List provider identity mappings | building-finance:read | API key |
| PUT | `/v1/api/building-finance/provider-identities` | Bind a provider identity | building-finance:write | API key |
| GET | `/v1/api/employees` | List employees | employees:read | API key |
| POST | `/v1/api/employees` | Create employee and invitation user | employees:write | API key |
| GET | `/v1/api/employees/{employeeId}` | Get employee | employees:read | API key |
| PATCH | `/v1/api/employees/{employeeId}` | Update employee | employees:write | API key |
| POST | `/v1/api/employees/{employeeId}/discontinue` | End-date employee and user login | employees:write | API key |
| GET | `/v1/api/time/worked-shifts` | Get worked shifts and reported entries | time:read | API key |
| GET | `/v1/api/time/summary` | Get worked-time and pay summary by employee | time:read | API key |
| GET | `/v1/api/expenses` | List expense headers and lines | expenses:read | API key |
| GET | `/v1/api/absences` | List vacations and absences | absences:read | API key |
| POST | `/v1/api/absences` | Create vacation or absence | absences:write | API key |
| GET | `/v1/api/absences/{absenceId}` | Get absence | absences:read | API key |
| PATCH | `/v1/api/absences/{absenceId}` | Update absence | absences:write | API key |
| DELETE | `/v1/api/absences/{absenceId}` | Delete absence | absences:write | API key |
| GET | `/v1/api/clients` | List CRM clients | clients:read | API key |
| POST | `/v1/api/clients` | Create CRM client | clients:write | API key |
| GET | `/v1/api/clients/{clientId}` | Get CRM client details | clients:read | API key |
| PATCH | `/v1/api/clients/{clientId}` | Update CRM client | clients:write | API key |
| GET | `/v1/api/clients/{clientId}/sites` | List sites for CRM client | sites:read | API key |
| POST | `/v1/api/clients/{clientId}/sites` | Create site for CRM client | sites:write | API key |
| PATCH | `/v1/api/clients/{clientId}/sites/{siteId}` | Update site for CRM client | sites:write | API key |
| GET | `/v1/api/clients/{clientId}/contacts` | List contacts for CRM client | contacts:read | API key |
| POST | `/v1/api/clients/{clientId}/contacts` | Create contact for CRM client | contacts:write | API key |
| GET | `/v1/api/contacts` | List CRM contacts | contacts:read | API key |
| PATCH | `/v1/api/contacts/{contactPointId}` | Update CRM contact | contacts:write | API key |
| GET | `/v1/api/locations` | List CRM site locations | locations:read | API key |
| GET | `/v1/api/sites` | List organization sites | sites:read | API key |
| POST | `/v1/api/sites` | Create organization site with location | sites:write | API key |
| GET | `/v1/api/sites/{siteId}` | Get organization site | sites:read | API key |
| PATCH | `/v1/api/sites/{siteId}` | Update organization site | sites:write | API key |
| GET | `/v1/api/sites/{siteId}/equipment` | List equipment | setup:read | API key |
| POST | `/v1/api/sites/{siteId}/equipment` | Create equipment | setup:write | API key |
| GET | `/v1/api/sites/{siteId}/equipment/{equipmentId}` | Get equipment | setup:read | API key |
| PATCH | `/v1/api/sites/{siteId}/equipment/{equipmentId}` | Update equipment | setup:write | API key |
| DELETE | `/v1/api/sites/{siteId}/equipment/{equipmentId}` | Delete equipment | setup:write | API key |
| GET | `/v1/api/compensations` | List compensation definitions | compensation:read | API key |
| POST | `/v1/api/compensations` | Create compensation definition | compensation:write | API key |
| POST | `/v1/api/employees/{employeeId}/compensations` | Assign compensation to employee | compensation:write | API key |
| GET | `/v1/api/materials` | List materials | materials:read | API key |
| POST | `/v1/api/materials` | Create material | materials:write | API key |
| GET | `/v1/api/materials/{materialId}` | Get material | materials:read | API key |
| PATCH | `/v1/api/materials/{materialId}` | Update material | materials:write | API key |
| GET | `/v1/api/suppliers` | List suppliers | suppliers:read | API key |
| POST | `/v1/api/suppliers` | Create supplier | suppliers:write | API key |
| GET | `/v1/api/suppliers/{supplierPartyId}` | Get supplier details | suppliers:read | API key |
| GET | `/v1/api/suppliers/{supplierPartyId}/employees` | List supplier employees | suppliers:read | API key |
| POST | `/v1/api/suppliers/{supplierPartyId}/employees` | Create supplier employee | suppliers:write | API key |
| PATCH | `/v1/api/suppliers/{supplierPartyId}/employees/{employeePartyId}` | Update supplier employee | suppliers:write | API key |
| GET | `/v1/api/suppliers/{supplierPartyId}/agreements` | List agreements for supplier | agreements:read | API key |
| GET | `/v1/api/agreements` | List agreements | agreements:read | API key |
| POST | `/v1/api/agreements` | Create agreement | agreements:write | API key |
| GET | `/v1/api/agreements/stats` | Get agreement expiry statistics | agreements:read | API key |
| GET | `/v1/api/agreements/{agreementId}` | Get agreement | agreements:read | API key |
| PATCH | `/v1/api/agreements/{agreementId}` | Update agreement | agreements:write | API key |
| DELETE | `/v1/api/agreements/{agreementId}` | Terminate agreement | agreements:write | API key |
| GET | `/v1/api/work-orders` | List CRM work orders | work-orders:read | API key |
| POST | `/v1/api/work-orders` | Create CRM work order | work-orders:write | API key |
| GET | `/v1/api/work-orders/{workOrderId}` | Get CRM work order | work-orders:read | API key |
| PATCH | `/v1/api/work-orders/{workOrderId}` | Update CRM work order | work-orders:write | API key |
| GET | `/v1/api/clients/{clientId}/work-orders` | List CRM client work orders | work-orders:read | API key |
| GET | `/v1/api/sites/{siteId}/work-orders` | List CRM site work orders | work-orders:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/statistics` | Get work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/clients/{clientId}/work-orders/statistics` | Get client work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/sites/{siteId}/work-orders/statistics` | Get site work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/clients/{clientId}/sites/{siteId}/work-orders/statistics` | Get client-site work order statistics | work-order-reports:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/report/pdf` | Download work order PDF report | work-order-reports:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/report/excel` | Download work order Excel report | work-order-reports:read | API key |
| GET | `/v1/api/work-orders/{workOrderId}/report/csv` | Download work order CSV report | work-order-reports:read | API key |
| GET | `/v1/api/clients/{clientId}/work-orders/statistics/report/pdf` | Download client work order statistics PDF report | work-order-reports:read | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meter-readings` | List apartment meter readings | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meter-readings` | Create apartment meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meters` | List configured apartment meters | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meters` | Create an apartment meter | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meters/{meterId}` | Update an apartment meter | building-management:write | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/meter-readings/{id}/corrections` | Correct an apartment meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/agreements` | List apartment ownership and tenancy agreements | building-ownership:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/agreements` | Create an apartment ownership or tenancy agreement | building-ownership:write | API key |
| PATCH | `/v1/api/building-management/apartment-agreements/{agreementId}` | Update an apartment agreement | building-ownership:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/financial-documents` | List canonical apartment bills | building-finance:read | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/apartments/{siteId}/payments` | List canonical apartment payments | building-finance:read | API key |
| GET | `/v1/api/building-management/financial-documents/{id}/details` | Get canonical bill details | building-finance:read | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/meters` | List communal building meters | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/meters` | Create communal building meter | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{buildingPartyId}/meters/{meterId}` | Update communal building meter | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/meter-readings` | List communal building meter readings | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/meter-readings` | Create communal building meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons` | List apartment owners, tenants, payers, and contacts | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons` | Create apartment person relationship | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons/{relationshipId}` | Update apartment person relationship | building-management:write | API key |
| DELETE | `/v1/api/building-management/buildings/{clientId}/apartments/{siteId}/persons/{relationshipId}` | End apartment person relationship | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors` | List house senior assignments for building | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors` | Assign house senior to building | building-management:write | API key |
| PATCH | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors/{relationshipId}` | Update house senior assignment | building-management:write | API key |
| DELETE | `/v1/api/building-management/buildings/{buildingPartyId}/house-seniors/{relationshipId}` | End house senior assignment | building-management:write | API key |
| PATCH | `/v1/api/building-management/meter-readings/{id}` | Update meter reading | building-management:write | API key |
| DELETE | `/v1/api/building-management/meter-readings/{id}` | Delete meter reading | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/financial-documents` | List building financial documents | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/financial-documents` | Create building financial document | building-management:write | API key |
| PATCH | `/v1/api/building-management/financial-documents/{id}` | Update financial document | building-management:write | API key |
| DELETE | `/v1/api/building-management/financial-documents/{id}` | Delete financial document | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/payments` | List building payments | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/payments` | Create building payment | building-management:write | API key |
| PATCH | `/v1/api/building-management/payments/{id}` | Update payment | building-management:write | API key |
| DELETE | `/v1/api/building-management/payments/{id}` | Delete payment | building-management:write | API key |
| GET | `/v1/api/building-management/buildings/{buildingPartyId}/tasks` | List building CRM tasks | building-management:read | API key |
| POST | `/v1/api/building-management/buildings/{buildingPartyId}/tasks` | Create building CRM task | building-management:write | API key |
| PATCH | `/v1/api/building-management/tasks/{id}` | Update building CRM task | building-management:write | API key |
| GET | `/v1/api/building-management/notifications` | List building notifications | building-management:read | API key |
| POST | `/v1/api/building-management/notifications` | Create or queue building notification | building-management:write | API key |
| PATCH | `/v1/api/building-management/notifications/{id}` | Update or send draft building notification | building-management:write | API key |
| DELETE | `/v1/api/building-management/notifications/{id}` | Delete draft building notification | building-management:write | API key |
| GET | `/v1/api/building-management/sync-attempts` | List building-management sync attempts | building-management:sync | API key |
| POST | `/v1/api/building-management/sync/{objectType}/{id}` | Synchronize one building-management object | building-management:sync | API key |
| GET | `/v1/api/inspections/buildings` | List inspection buildings | inspections:read | API key |
| GET | `/v1/api/inspections/buildings/{clientId}/history` | List building inspection history | inspections:read | API key |
| GET | `/v1/api/inspections/buildings/{clientId}/work-orders` | List inspection work orders for building | inspections:read | API key |
| GET | `/v1/api/inspections/work-orders/{workOrderId}/details` | Get section-scoped inspection details for a work order | inspections:read | API key |
| GET | `/v1/api/inspections/act-templates` | List inspection act templates | inspections:read | API key |
| GET | `/v1/api/inspections/acts` | List inspection acts | inspections:read | API key |
| POST | `/v1/api/inspections/acts` | Create inspection act | inspections:write | API key |
| GET | `/v1/api/inspections/acts/{actId}` | Get inspection act details | inspections:read | API key |
| PATCH | `/v1/api/inspections/acts/{actId}` | Update inspection act | inspections:write | API key |
| PUT | `/v1/api/inspections/acts/{actId}/values` | Replace inspection act values | inspections:write | API key |
| POST | `/v1/api/inspections/acts/{actId}/evidence` | Add inspection evidence metadata | inspections:write | API key |
| GET | `/v1/api/inspections/acts/{actId}/defects` | List inspection defects | inspections:read | API key |
| POST | `/v1/api/inspections/acts/{actId}/defects` | Create inspection defect | inspections:write | API key |
| GET | `/v1/api/inspections/acts/{actId}/work-orders` | List work orders linked to inspection act | inspections:read | API key |
| POST | `/v1/api/inspections/acts/{actId}/work-orders` | Create work order from inspection act | inspections:write, work-orders:write | API key |
| POST | `/v1/api/inspections/acts/{actId}/section-work-orders` | Create section work orders for one inspection act | inspections:write, work-orders:write | API key |
| GET | `/v1/api/inspections/acts/{actId}/statistics` | Get inspection act rollup statistics | inspections:read | API key |
| GET | `/v1/api/inspections/acts/{actId}/versions` | List inspection act versions | inspections:read | API key |
| GET | `/v1/api/attachments` | List attachment metadata | attachments:read | API key |

## MCP tools

All ten tools are read-only. The public catalogue does not grant execution access; tools/list is filtered to the current grant.

| Tool | Audience | Scope | Backend mapping | Example arguments |
| --- | --- | --- | --- | --- |
| `get_property_inspection_details` | STAFF | inspections:read | GET `/v1/api/mcp/staff/inspections/:actId` | `{"act_id":"70"}` |
| `list_properties` | RESIDENT | resident:properties:read | GET `/v1/api/mcp/resident/properties` | `{"skip":0,"take":20}` |
| `list_maintenance_requests` | RESIDENT | resident:requests:read | GET `/v1/api/mcp/resident/properties/:siteId/requests` | `{"site_id":"50","skip":0,"take":20}` |
| `get_maintenance_request_details` | RESIDENT | resident:requests:read | GET `/v1/api/mcp/resident/properties/:siteId/requests/:id` | `{"site_id":"50","request_id":"9"}` |
| `list_supplier_opportunities` | SUPPLIER | supplier:bids:read | GET `/v1/api/mcp/supplier/bids` | `{"page":0,"take":20}` |
| `get_supplier_bid_status` | SUPPLIER | supplier:bids:read | GET `/v1/api/mcp/supplier/bids/:bidRequestId/status` | `{"bid_request_id":"9"}` |
| `list_work_orders` | STAFF | work-orders:read | GET `/v1/api/work-orders` | `{"page":0,"take":20}` |
| `get_work_order_details` | STAFF | work-orders:read | GET `/v1/api/work-orders/:workOrderId` | `{"work_order_id":"9"}` |
| `list_contractors` | STAFF | suppliers:read | GET `/v1/api/suppliers` | `{"skip":0,"take":20}` |
| `list_property_inspections` | STAFF | inspections:read | GET `/v1/api/mcp/staff/inspections` | `{"skip":0,"take":20}` |

## Pagination and results

MCP take: 1–50, default 20. skip: row offset 0–100000, default 0. page: zero-based 0–2000, default 0. IDs: positive decimal strings up to 16 digits. Work-order page forwards as the backend page-index skip; supplier page converts to an offset; other lists use row offsets. property_id is a building party ID; resident site_id is an apartment/site ID. Unknown arguments are rejected. Lists return success, data, metadata and pagination (skip, take, total, hasMore). Errors set isError with a bounded category and correlation ID. Private contacts, notes, compensation, attachments, precise locations and competitor responses are excluded. See catalogue for exact required, optional and nullable fields.

REST pagination and filters vary by operation: consult its parameters in the local OpenAPI. Do not assume skip is always a row offset or that every declared shared filter is implemented.

## Supporting protocol, OAuth and consent methods

See [setup and supporting methods](https://connectme.work/integration-docs/integration-setup.md) and [missing capabilities and release gates](https://connectme.work/integration-docs/integration-gaps.md).


---

# 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](https://connectme.work/integration-docs/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](https://connectme.work/integration-docs/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](https://connectme.work/integration-docs/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`.


---

# Missing capabilities and verification gaps

Reviewed 8 November 2026 against local `connect-api` source and its MCP verification ledger. “Missing” below means no established external/MCP contract was found; related internal application functionality may exist. Website changes do not implement these backend capabilities.

## Missing or partial MCP tools

| Requested capability | Current gap / dependency |
| --- | --- |
| `get_employee_schedule` | No external planned-shift mapping; worked shifts are not planned schedules. |
| `get_employee_availability` | No established availability/date/department contract; absences alone do not prove availability. |
| `get_unfilled_shifts` | No bounded external unassigned-shift contract. |
| `get_scheduling_conflicts` | No existing conflict-result contract exposed; gateway must not invent scheduling rules. |
| `get_employee_time_reports` | Partial REST candidate: worked shifts and summary exist, but pay exclusion, actual filter behavior, date semantics and bounds need verification. No MCP tool. |
| `get_overdue_work_orders` | Generic list does not establish canonical overdue rules/filter. |
| `get_work_order_history` | No dedicated bounded operational-history contract. |
| `get_field_worker_status` | No current operational-status contract; employee lists and shifts do not establish status or GPS permission. |
| `get_contractor_availability` | No contractor/date availability projection. |
| `list_contractor_assignments` | Agreements/general work orders do not establish assignments by contractor/date. |
| `list_property_defects` | Partial: REST has act-level defects, not bounded property-level traversal/filtering under current actor scope. |
| `get_property_defect_details` | No direct external defect-ID detail contract found. |
| `list_supplier_bids_for_property` | Internal procurement exists; external delegated property/audience-safe projection is absent. Supplier tools only expose invited opportunities and own status. |
| `get_property_maintenance_history` | Inspection history and work-order lists exist separately; no unified authorized chronology. |
| Operational write tools | No MCP create/update/delete operations. REST writes do not imply MCP write availability. |

Source: sibling `docs/mcp-gateway-api-mapping.md`. New tools need exact endpoint, schemas, minimized fields, current authorization, pagination/time semantics and passing persistence/protocol/security evidence before discovery.

## API documentation gaps still present upstream

The fresh local audit passes route/method/scope parity for 144 business methods (146 including metadata). That audit does not certify every response field or handler semantic.

- Several JSON reads have unspecified success fields, including GET `/time/worked-shifts`, `/time/summary`, `/expenses`, `/absences`, `/absences/{absenceId}`, `/compensations`, `/work-orders/{workOrderId}`, `/inspections/acts/{actId}`, `/inspections/acts/{actId}/versions`, and `/attachments`. See the complete generated [response schema review](https://connectme.work/integration-docs/integration-schema-gaps.md). Local copies preserve the source rather than invent fields.
- Report downloads intentionally use binary responses. PDF upload success statuses have no response content schema; upstream should document whether each response is empty or returns metadata. A response without a JSON schema alone is not a missing method.
- Worked-shift shared query fields include filters that its SQL does not all apply; count is page length. Pagination is not uniform across REST operations. MCP adapters document their own normalized pagination.
- Delegated OpenAPI projections mainly describe success; error shape/status coverage is incomplete. Use MCP catalogue error semantics and do not assume the API-key error description applies to OAuth tokens.
- This snapshot documents the external API and MCP supporting routes, not every internal application route or every API Portal management action. Staff administration remains in the authenticated staff application.

## Open deployment and release gates

The source ledger reports local HTTP/SDK/PostgreSQL/Redis and rendered consent component coverage for all ten tools. Its fixtures do not certify full production migrations/triggers, provider-backed resident/supplier login or a deployed browser journey.

Outstanding evidence: hosted CI; actual image build/publication; production-like startup with full migrations; stable HTTPS gateway/issuer and exact external-client registration/callback interoperability; proxy/egress/TLS policy; measured load and replica limits; alerts; secret rotation; rollback. Dynamic client registration and client metadata documents are not implemented. There is no verified deployed gateway URL or client connection result from this website task. No app listing, review or production enablement is claimed.

The upstream ledger records 11 supplier dependency audit findings (9 moderate, 2 high). This is a reported historical local result, not a fresh dependency audit from this website task.

## Website follow-up

The previous feasibility document incorrectly described the now-implemented gateway as absent; it is marked superseded. Integration highlights are translated in all 13 site languages; technical method/schema documentation remains English and the developer page says so. A full technical-reference translation remains future work. Local snapshots must be refreshed when the backend changes; normal website builds deliberately do not depend on sibling repositories.


---

# Upstream response schema review

Generated 2026-11-08 from API 1.3.0. These are documentation review candidates, not proof of runtime failures. Intentional binary or empty responses need separate review.

| Method | Path relative to /v1/api | Success status | Gap |
| --- | --- | --- | --- |
| POST | `/building-finance/imports/{id}/document` | 200 | No response content schema (review binary/no-body intent) |
| POST | `/building-finance/imports/{id}/document` | 201 | No response content schema (review binary/no-body intent) |
| GET | `/time/worked-shifts` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/time/summary` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/expenses` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/absences` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/absences/{absenceId}` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/compensations` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/work-orders/{workOrderId}` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/work-orders/{workOrderId}/report/pdf` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/work-orders/{workOrderId}/report/excel` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/work-orders/{workOrderId}/report/csv` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/clients/{clientId}/work-orders/statistics/report/pdf` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/inspections/buildings` | 200 | Unspecified object fields |
| GET | `/inspections/buildings/{clientId}/history` | 200 | Unspecified object fields |
| GET | `/inspections/work-orders/{workOrderId}/details` | 200 | Unspecified object fields |
| GET | `/inspections/act-templates` | 200 | Unspecified object fields |
| GET | `/inspections/acts` | 200 | Unspecified object fields |
| GET | `/inspections/acts/{actId}` | 200 | No response content schema (review binary/no-body intent) |
| GET | `/inspections/acts/{actId}/defects` | 200 | Unspecified object fields |
| POST | `/inspections/acts/{actId}/section-work-orders` | 201 | Unspecified object fields |
| GET | `/inspections/acts/{actId}/statistics` | 200 | Unspecified object fields |
| GET | `/inspections/acts/{actId}/versions` | 200 | Unspecified object fields |
| GET | `/attachments` | 200 | No response content schema (review binary/no-body intent) |