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 task write.

1. Add https://api.firstaiemployee.com/mcp in a compatible AI host.
2. Sign in to First AI Employee and approve only the scopes needed for the workflow you want to test.
3. Ask the host to confirm your business with get_business_identity before reading or preparing any work.
4. Review every prepared task in the host. Nothing is created 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 and token exchange. A token for any other resource is rejected.
• 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.

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.

Version 1 tool catalog

Read tools return minimized, bounded records. Creating a task, creating a form, and publishing a form are the only mutations, and each one waits for your approval. Write tools are omitted from discovery unless the write gate is enabled.

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 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_business_identity","arguments":{}}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Synthetic Get connected business 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 and changes nothing. The agent must show that exact preview and obtain explicit approval. commit_task_create and commit_form_change accept no editable fields and can apply only the approved change. reject_task_create and reject_form_change close the preview without changing anything.

Explicit boundaries

• No tool sends a message, places a call, posts a review reply, changes billing, or changes receptionist behavior.
• 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.
• Calls require an active AI Receptionist entitlement. Review data requires the corresponding Chat & Replies capability.
• MCP access has no separate price. Paid capabilities follow the same published product pricing and entitlements used elsewhere.

Account requirements

MCP is live for authenticated First AI Employee owners through compatible CIMD hosts. Connection is self-service. Each visible tool still requires the matching OAuth scope, live account permission, module, and product entitlement. Consequential task creation also requires explicit approval of the exact stored preview.

Errors and retries

The code inside the MCP error content controls recovery. A host should preserve the returned request ID when asking for support and retry only when retryable is true.

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