Connect an assistant with MCP

MCP Server lets an external assistant use Contractor Codex tools to read records and perform permitted actions. This is an incoming connection to the portal, separate from the outgoing provider connection used by built-in chat.

Set up the connection

1. Have an account owner open MCP Server and enable it for your organization.
2. Have an account owner create an API key. Review included read access and select only the action permissions needed.
3. Copy the endpoint and the matching client configuration from the setup page into your assistant.
4. Supply the key as an Authorization bearer token. Keep it out of prompts, public files, screenshots, and URLs.
5. Use the page's connection test, then ask the connected assistant to call get_context before starting work.

The endpoint is your portal origin followed by /api/mcp; it uses Streamable HTTP. Staging and production are separate environments—copy the endpoint and key from the environment you intend to use. Third-party clients differ in how they configure remote MCP and headers; use a client that supports this connection.

Bearer authentication, not a browser login

The MCP transport validates the portal API key. An open Clerk browser session is not required, and signing out of the browser does not revoke the key.

The key must be active, unexpired, and permitted by any configured IP restrictions. Its creator must still have the required owner authority. The organization's MCP switch must also be enabled.

The transport reports X-MCP-Auth-Status as authenticated or unauthenticated. A valid key can still receive a permission or feature-disabled error. This is separate from Clerk's browser sign-in state; a Clerk session header is not evidence of MCP authorization.

Revoke a key if it is lost or exposed. Do not rely on signing out, hiding the key, or disabling only your assistant client.

Understand the tool catalog

The MCP page has Setup, Connect, Tools, and Audit & safety tabs. The catalog on Tools is generated from the current tool registry. Use it for current tool names, input schemas, permission groups, and confirmation badges rather than a fixed tool count in a guide.

Tools are still subject to record scope, current permissions, billing state, and integration requirements. A permission checkbox is not a promise that every action is available for every record.

The tool catalog also includes operations that can change state without a write-group permission, such as supported Advisor state changes or project-thread replies. Read the tool description before treating a key as strictly read-only.

Information deliberately not exposed

Agent tools do not expose raw provider secrets. get_settings and update_setting use curated settings, not unrestricted access to configuration. Provider keys, subscription fees, and other excluded settings must be managed through their appropriate pages.

The MCP Advisor view excludes bank-feed-derived money findings. The old codex_money_summary tool is retired; use the authenticated Codex pages for bank-feed information. The current catalog, not an assistant's memory of an old tool, determines what is available.

The approval workflow

Tools that require confirmation use two separate calls:

1. The assistant submits the intended action and receives confirmation_required, a preview, and a short-lived token.
2. It shows you the preview and waits for your approval.
3. Only after approval does it repeat the same action and parameters with that token.
4. Read the result to confirm what actually happened.

The token is tied to the calling key, action, and parameters. Changing the recipient, amount, record, or other parameters requires a fresh preview. MCP confirmation tokens normally expire after 60 seconds. Request a new preview if one expires.

Where supported, dry_run="true" previews without executing or issuing an approval token. Not every tool supports dry run or confirmation; follow its schema.

Approving a draft does not authorize sending it. For example, creating a local invoice draft requires its own reviewed action, and send_invoice requires a new send preview and approval. The same care applies to quote and contract recipients and signature behavior.

Some routine internal actions apply directly—for example, supported session updates and private client notes. Tell the assistant precisely what you want changed.

Payment and project-pricing limits

mark_paid records an existing receipt, not a new customer charge. For a Stripe-backed invoice it requires a verified full settlement; partial external payments, combined invoices, and tax or credit mismatches need review in Billing/Stripe. A provider error is not proof of payment. If settlement succeeded but the local update needs recovery, inspect the existing invoice before requesting a fresh preview—do not create a second receipt. See Recording an existing invoice as paid.

Project tools do not allow a new separately priced project-retainer selection while its base-fee billing is unsupported. They preserve unchanged historical agreements during unrelated edits. Supported client-level retainers, hourly/block/fixed project pricing, and recurring provider-cost disclosures remain distinct workflows. See Project-retainer pricing.

Follow-up questions and recovery

A useful workflow is: ask who owes money, inspect the source invoices, choose exact invoices, preview a reminder, then approve that specific send. Do not let “everyone” silently expand into an unreviewed group.

Supported reminder batches are bounded to 1–10 specific past-due invoices. Results can include completed, skipped, failed, or uncertain items. Records that changed or were already paid can be skipped.

If a connection drops, ask the assistant to use get_task_status with the original task or request ID before retrying a supported durable action. Recovery is scoped to the organization and key creator and checks current permissions. Reading status does not retry, renew, or execute the action.

An uncertain result means check the actual record or delivery history first. It does not mean “failed safely”; blindly retrying could duplicate work.

Quoting from the field or an external assistant

The quoting tools use the shared quoting workflow, including customer-price references, review questions, optional items, recurring business services, and provider-direct costs. AI prices and supplier listings still need review; a drafted price is not a verified supplier order.

A temporary draft or PDF preview is not a saved customer quote and does not send email or start billing. Saving a quote, sending it, and the client's acceptance are distinct steps. See Field Mode for the phone interface.

Troubleshooting

• Unauthorized: check the full bearer key, environment, expiry/revocation, and the creator's current access.
• Authenticated but denied: check the MCP switch, requested permission, record scope, and integration or subscription requirements.
• Missing tool: reconnect or refresh the external client's tool list and compare it with the live catalog.
• Expired approval: create a fresh preview; do not reuse the old token.
• Interrupted send/payment: inspect the durable task and affected record before retrying.
• Model cannot use tools: MCP provides tools, but the external assistant must support and correctly use them. The portal's customer model setting does not choose that external model.

Portal tool calls are audited, but an activity entry alone is not proof that an external email or payment was delivered. Use the action receipt and provider/record state when investigating.