Use First AI Employee from a compatible AI agent

Protected resource

Discovery metadata

Protected resource metadata

https://api.firstaiemployee.com/.well-known/oauth-protected-resource

Authorization server metadata

https://api.firstaiemployee.com/.well-known/oauth-authorization-server

Start here as a business owner

Connect from any compatible AI host that supports secure MCP OAuth discovery. The host handles the protocol details while you stay in control of the business connection and every reviewed write.

1. Add https://api.firstaiemployee.com/mcp in a compatible AI host.
2. Sign in to First AI Employee and approve the requested read and write permissions in one consent screen. Clients configured for mcp:full expand it to the exact concrete scopes in the current catalog, and the shorthand is never stored on the grant.
3. Ask the host to confirm your business with get_business_identity before reading or preparing any work.
4. Review every prepared change in the host. Nothing is committed until you explicitly approve the exact stored preview.

Connection flow

1. A compatible host identifies itself through a reviewed static registration or a secure Client ID Metadata Document.
2. The host connects to the protected resource URL and discovers the First AI Employee authorization server from standards-based metadata.
3. The business owner signs in and approves a fixed list of OAuth scopes for one business.
4. Start with get_business_identity to confirm the connected business and currently available capabilities. The owner can revoke the connection from Connected Apps.

Protocol and authentication

The public resource uses MCP Streamable HTTP. Authorization is OAuth 2.0 Authorization Code with PKCE S256 and exact resource binding.

• Send resource=https://api.firstaiemployee.com/mcp during authorization, code exchange, and refresh. Use this exact URL without a trailing slash. A token for any other resource is rejected.
• Interactive access tokens expire after one hour. Refresh tokens rotate on every successful refresh and expire after 90 days without renewal. Save both returned tokens together and serialize refreshes for each connection. Reusing an old refresh token revokes the authorization; reconnect if refresh returns invalid_grant.
• The current source protocol is 2026-07-28 with server/discover. Older supported clients use initialize. Let an MCP SDK negotiate the version; do not mix request headers or metadata from different protocol versions.
• Public clients use PKCE S256. Redirect URIs must exactly match a declared callback. HTTPS is required except for the permitted native-app loopback HTTP pattern.
• Bearer tokens belong in the Authorization header, never in a URL, log, analytics event, or tool argument.
• Tool discovery reflects the live grant, account eligibility, product entitlements, and write availability.
• Most list tools use bounded keyset pagination. Pass next_cursor back unchanged with the same tool and filters. Discard an invalid or mismatched cursor and restart the list. list_automation_rules uses next_offset instead; pass it as offset to fetch the next page.

Universal clients with CIMD

A public MCP client can use an HTTPS metadata-document URL as its OAuth client_id. First AI Employee advertises this as client_id_metadata_document_supported in its authorization-server metadata, then retrieves and validates the document. A compatible client does not need a manually issued client ID or client secret.

• The client_id must be the same public HTTPS URL returned in the document. The URL cannot contain credentials, a query, a fragment, an IP-literal host, or a root-only path.
• Declare token_endpoint_auth_method as none. Do not send a client secret. Every authorization request still requires state, PKCE S256, and the exact MCP resource parameter.
• HTTPS callbacks must match a declared redirect URI exactly. Declared localhost, 127.0.0.1, and IPv6 loopback HTTP callbacks may use an ephemeral port, but the host, path, and query must still match.
• The First AI Employee account owner sees the client identity, return destination, and requested scopes before deciding whether to allow the connection.

{
  "client_id": "https://client.example/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "redirect_uris": [
    "http://localhost/oauth/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ]
}

This flow supports the localhost callback pattern used by desktop and command-line MCP clients such as Claude Code. Protocol compatibility is implemented, but an authenticated Claude Code connection has not yet been completed.

Unattended reads with a service account

A business owner can create a long-lived MCP client credential through the authenticated owner API. It exchanges for 15-minute access tokens with no refresh token. This path needs no developer account, but it is deliberately narrower than interactive owner-approved MCP.

• Only the unimpersonated business owner with settings permission can create, inspect, change, rotate, or revoke a service account. It is always bound to that owner's business.
• The credential is MCP-only and read-only. Its safe scopes allow only eligible bounded reads. It cannot use document-template, signature, automation-setup, or automation-notification preference reads, any prepare, commit, or reject tool, or any Client API route.
• Create and rotate show the client secret once; First AI Employee stores only its hash. The credential has no automatic expiry today. Rotate or revoke it when it should stop working.
• A token request may omit scope to receive the account's allowed set or request a smaller subset. The default issuance limits are 30 token requests per minute and 500 per UTC day. Normal MCP limits and account checks still apply afterward.
• The token endpoint implements client_credentials for service accounts, but authorization-server metadata does not currently advertise that grant. Configure this machine credential explicitly rather than relying on discovery.
• Changing scopes revokes existing grants and tokens but keeps the current client secret. Rotation replaces the secret immediately and revokes every existing grant and token. Account revocation is irreversible.

Current service-account scope catalog

POST /oauth/token HTTP/1.1
Host: api.firstaiemployee.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_SERVICE_ACCOUNT_CLIENT_ID_AND_SECRET

grant_type=client_credentials&
scope=business%3Aread%20front_desk%3Atasks%3Aread&
resource=https%3A%2F%2Fapi.firstaiemployee.com%2Fmcp

The backend owner API implements this lifecycle, but the customer dashboard does not yet provide a creation or management screen. These first-party owner routes are not the stable Client API. Do not copy or share a dashboard session token to automate them.

Version 1 tool catalog

The public OAuth source catalog contains 92 tools: 46 bounded reads and 46 reviewed write tools. Form draft editing and contact-segment prepare/commit/reject are dashboard-only and do not add OAuth permissions. Task creation, contact upsert, form creation or publishing, signature-send approval, internal automation setup, automation notification preferences, scheduling configuration, business profile changes, and Front Desk setup use stored previews. AI cannot grant browser permission or subscribe a device. Signature approval records no delivery by itself. A deployed connection discovers only the tools allowed by its gates, grant, account, modules, and entitlements.

What a host receives

Successful tools return ordinary MCP content plus schema-validated structuredContent. The values below are synthetic, but the envelope and field names match the public version 1 contract.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Connected to Demo Plumbing."
      }
    ],
    "structuredContent": {
      "schema_version": 1,
      "request_id": "req_demo_01",
      "business": {
        "name": "Demo Plumbing",
        "timezone": "America/Chicago",
        "front_desk_level": "essential",
        "receptionist_status": "not_active"
      },
      "available_capabilities": [
        "front_desk.tasks.read",
        "front_desk.contacts.read",
        "tasks.prepare",
        "tasks.commit"
      ]
    },
    "isError": false,
    "_meta": {
      "request_id": "req_demo_01",
      "replayed": false
    }
  }
}

An expected authorization, eligibility, validation, approval, conflict, limit, or dependency failure is an MCP tool result with isError: true. Its strict JSON error envelope is serialized in content[0].text, and structuredContent is omitted so the success output schema is not falsely claimed.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"schema_version\":1,\"error\":{\"code\":\"ACCOUNT_NOT_ELIGIBLE\",\"message\":\"This account is not yet eligible for that tool.\",\"retryable\":false,\"request_id\":\"req_demo_02\"}}"
      }
    ],
    "isError": true
  }
}

Safe request builder

Choose a tool and generate a local example. The builder never asks for credentials and never executes a request.

curl 'https://api.firstaiemployee.com/mcp' \
  --request POST \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: tools/call' \
  --header 'Mcp-Name: read_front_desk_state' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_front_desk_state","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"fae-docs-example","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Synthetic Front desk state result"
      }
    ],
    "structuredContent": "<validated against the selected tool output schema>",
    "isError": false
  }
}

How every write stays reviewable

A prepare tool stores a fingerprinted preview for 15 minutes without applying the proposed business change. Show the exact returned preview, including any automation rehearsal and future effects, and obtain explicit approval. Use its draft_id, version, and fingerprint in the matching commit tool with human_confirmed: true. Commit tools accept no replacement business fields. Reject closes the preview without applying it. Example draft IDs and fingerprints below are placeholders; replace them with the actual prepare result.

Signature-request delegation

An owner can authorize one connected MCP app to prepare and record approval of signature.send within a narrow policy. This is approval delegation for a request workflow, not delegation of a human signature. prepare_signature_send and commit_signature_change never email the envelope and never sign for the owner or a recipient.

1. The owner creates the delegation in Documents & signatures for an eligible connected MCP app whose grant includes signatures:prepare and signatures:commit.
2. The grant is bound to one business, OAuth grant, client, and agent. It expires within 90 days and can be revoked immediately or emergency-revoked with the other live signature delegations.
3. The owner sets 1 to 5 recipients per envelope, 1 to 100 actions per day, and an optional document-value ceiling. Preparation fails closed when the live envelope or limits do not match.
4. Every action still requires the exact 15-minute preview, matching version and fingerprint, an idempotency key unique to that logical operation, and human_confirmed: true.
5. A successful commit returns approved_not_sent with no affected records. A separate human-controlled workflow must send the request, and only the human recipient signs it.

{
  "prepare": {
    "tool": "prepare_signature_send",
    "arguments": {
      "envelope_id": "00000000-0000-4000-8000-000000000006",
      "idempotency_key": "signature-demo-prepare-001"
    }
  },
  "exact_preview": {
    "action": "signature.send",
    "delivery_method": "email",
    "recipient_count": 1,
    "commit_effect": "record_approval_only"
  },
  "commit_after_human_confirmation": {
    "tool": "commit_signature_change",
    "arguments": {
      "draft_id": "00000000-0000-4000-8000-000000000001",
      "expected_draft_version": 1,
      "expected_fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "human_confirmed": true,
      "idempotency_key": "signature-demo-commit-001"
    }
  },
  "receipt": {
    "outcome": "committed",
    "envelope": {
      "status": "ready",
      "dispatch_state": "approved_not_sent"
    },
    "affected_records": []
  }
}

Recovery and revocation

• If the grant is missing, expired, revoked, or no longer matches the OAuth connection, ask the owner to create a new delegation. Do not retry automatically.
• If the envelope, grant limits, draft version, or fingerprint changed, discard the draft and prepare a fresh preview for review.
• If the draft expired, prepare again. If the request was rate-limited or a dependency was unavailable, retry only when the returned error says retryable and respect retry_after_seconds when present.
• Use the same idempotency key only to replay the same logical prepare or commit request. A changed payload needs a new key.

Explicit boundaries

• No tool sends a message, places a call, posts a review reply, or changes billing. Approved profile and scheduling changes affect the business information and scheduling behavior used by the receptionist.
• No tool creates a human signature or signs a document. Signature commit records approved_not_sent only.
• The connected customer is derived from the access token. No tool accepts a customer ID.
• Call results exclude transcripts and recordings. Results use allowlisted fields and bounded pagination.
• Booking tools read bookings the business already took, and the calendars it schedules on. They do not return live free or busy time, and they cannot create, move, or cancel a booking. Live availability comes from the connected calendar, not from this surface.
• Calls require an active AI Receptionist entitlement. Review data requires the corresponding AI Chat & Replies capability.
• MCP access has no separate price. Paid capabilities follow the same published product pricing and entitlements used elsewhere.

Account requirements

The source supports self-service owner authorization through compatible CIMD hosts. Actual use still requires an MCP-enabled deployment, public-account or pilot eligibility, a usable account, the matching OAuth scope, module, and product entitlement. Every consequential change also requires the write gate and explicit approval of the exact stored preview.

Errors and retries

Read isError and the code inside content[0].text even when HTTP succeeds. Preserve request_id for support. Retry only when retryable is true and honor retry_after_seconds. For the same logical prepare or commit retry, keep the same arguments and idempotency_key; use a different key for a new operation. A timeout does not prove a write failed, so do not create a new mutation to compensate automatically.

Static host registration and connection support are reviewed manually. Compatible CIMD clients can identify themselves through their metadata URL.