--- title: "Aila Model Context Protocol (MCP)" url: https://docs.aila.fyi/integrations/aila-mcp source: https://docs.aila.fyi/llms.txt --- # Aila Model Context Protocol (MCP) Connect ChatGPT, Claude, Codex, Cursor, and other MCP clients to Aila. The remote server uses **streamable HTTP** and **OAuth 2.1** (PKCE and Dynamic Client Registration). Ask Aila, the AI loan officer assistant, and this server use one shared tool registry, so most tools are the same. Remote URL (POST only): ```text https://app.aila.fyi/api/mcp ``` Do not open this URL in a browser as a page. A GET request returns HTTP 405. That response is expected. The server accepts streamable HTTP POST. There is no SSE route. `https://app.aila.fyi/api/mcp/sse` returns HTTP 404. > Do not open this URL in a browser as a page. A GET request returns HTTP 405. That response is expected. The server accepts streamable HTTP POST. There is no SSE route. --- ## What you can do The server covers **calls**, **contacts**, **charts**, **account setup**, and **your own settings**. If your organization has loan files turned on, it also covers **loan files**, **LOS work** (ARIVE and LendingPad), and **loan agent runs**. Without loan files, the server does not offer the loan tools. Each tool name starts with its area: `calls_`, `contacts_`, `team_`, `chart_`, `setup_`, `me_`, `loan_`, or `aila_`. The tables below show the main tools in each area. They are not the full list. Your client shows the live list for your connection. Treat that list as the source of truth. ### Calls and contacts | Tool | What it does | | :--- | :--- | | `calls_list` | Lists recent calls. | | `calls_search` | Finds calls by contact, caller, date, call type, tag, or duration. | | `calls_get_details` | Returns the summary and extracted data of one call. | | `calls_get_transcript` | Returns the transcript of one call, with speaker labels. | | `calls_lookup_contact` | Returns the call history of one contact. | | `calls_search_transcript_evidence` | Finds the transcript lines that answer a question. | | `calls_analyze_transcripts` | Reads a sample of calls to find call types, suggest fields to save, and suggest task triggers. | | `calls_get_scorecard_results` | Returns scorecard scores. Shows a scorecard card. | | `calls_find_follow_up_candidates` | Finds contacts that need a follow-up. | | `calls_correct_value` | Changes one extracted value on a call. Change. | | `contacts_merge` | Merges two contact records. Change. | | `team_get_performance` | Returns call metrics for each team member. | ### Charts | Tool | What it does | | :--- | :--- | | `chart_generate` | Makes a chart from call data. Shows a chart card. | | `chart_preview_extracted_metric` | Tries a new metric on past calls before you save it. | | `chart_promote_metric` | Saves a previewed metric as a field on future calls. Change. | | `chart_save` | Saves a chart to your dashboard. Change. | ### Account setup | Tool | What it does | | :--- | :--- | | `setup_get_status` | Shows what is connected and what is missing. Start here. | | `setup_get_ingestion_diagnostics` | Tells why calls do not arrive, and what to do. | | `setup_get_recipe` | Gives the steps to connect one product. | | `setup_get_configuration_skill` | Returns the full setup guide. | | `setup_create_scorecard`, `setup_update_scorecard` | Adds or changes a scorecard. Change. | | `setup_create_dataset`, `setup_update_dataset` | Adds or changes the data Aila pulls from calls. Change. | | `setup_create_routing_rule`, `setup_create_task_trigger` | Adds a call routing rule or a CRM task trigger. Change. | | `team_invite_member` | Invites a teammate by email. Change. | ### Your own settings | Tool | What it does | | :--- | :--- | | `me_list_call_views`, `me_save_call_view`, `me_update_call_view` | Lists, saves, and changes your saved filters on the Calls page. | | `me_get_permission_mode`, `me_set_permission_mode` | Reads or sets how often Ask Aila asks you before it makes a change in the Aila app. It does not change what ChatGPT or Claude asks. | ### Loan files (when turned on) | Tool | What it does | | :--- | :--- | | `loan_list_files`, `loan_find_borrower` | Finds a loan file by borrower. | | `loan_get_file` | Returns the full state of a loan file. Shows a loan file card. | | `loan_get_missing_docs` | Lists the documents that are still missing. Shows a missing documents card. | | `loan_read_document`, `loan_get_document_text` | Reads one document page, or its extracted text. | | `loan_upload_document`, `loan_classify_documents` | Adds a document and sorts it. Change. | | `loan_update_application_field` | Changes one field on the 1003. Change. | | `loan_draft_email`, `loan_draft_sms` | Writes a borrower message as a draft. Nothing is sent. | | `loan_approve_draft`, `loan_send_message` | Approves a draft, then sends it. Change. | | `loan_lookup_los_loans`, `loan_import_los_loan` | Finds a loan in ARIVE or LendingPad, and imports it as an Aila loan file. Import is a change. | | `loan_write_arive_loan_status`, `loan_push_to_lendingpad` | Writes to the LOS. Change. | ### Loan agent runs (when loan files are turned on) | Tool | What it does | | :--- | :--- | | `loan_start_agent_run` | Starts an AI agent on a loan file. Change. | | `loan_get_agent_run` | Shows the state, report, and latest events of a run. | | `loan_stop_agent_run` | Stops a run. Change. | The agent only proposes changes. A person approves or rejects them in the Aila app. ### Help and undo | Tool | What it does | | :--- | :--- | | `aila_search_docs` | Searches these docs. | | `aila_search_web` | Searches the public web for a fact, such as a company's NMLS number. | | `aila_undo_action` | Undoes one change. See [Undo a change](#undo-a-change). | ### Cards in the chat Four tools return a card that ChatGPT and Claude show in the chat (MCP Apps): - `chart_generate`: a chart. - `calls_get_scorecard_results`: scorecard results. - `loan_get_file`: a loan file summary. - `loan_get_missing_docs`: the missing documents. A client without MCP Apps shows the same data as text. ### Old tool names Before October 23, 2026, some tools had other names, for example `list_calls`, `search_calls`, `get_call_details`, `get_call_transcript`, `lookup_contact`, `search_contacts`, and `get_team_performance`. The old names still work until **December 22, 2026**. After that date, use the new names: | Old name | New name | | :--- | :--- | | `list_calls` | `calls_list` | | `search_calls` | `calls_search` | | `get_call_details` | `calls_get_details` | | `get_call_transcript` | `calls_get_transcript` | | `lookup_contact` | `calls_lookup_contact` | | `search_contacts` | `calls_search_contacts` | | `get_team_performance` | `team_get_performance` | | `get_loan_file` | `loan_get_file` | | `find_borrower` | `loan_find_borrower` | --- ## How changes run A tool that changes data runs when the client calls it. The client decides when to ask you to confirm: - ChatGPT asks before each tool that is not read-only. - Claude asks before each tool that is marked destructive. Each change tool tells the client if it is read-only, if it is destructive, and if it sends data outside Aila (for example a borrower message). The client uses these marks to decide when to ask you. Some actions need more than the client's confirmation: - **Borrower messages.** Aila always writes a draft first (`loan_draft_email` or `loan_draft_sms`). The draft must be approved (`loan_approve_draft`) before `loan_send_message` can send it. - **LOS writes.** A write to ARIVE or LendingPad needs your approval and a confirmation inside the tool. - **Loan file deletes** are not available to OAuth or API key connections. Aila records each change in its action log, with the name of the client that made it. ### Undo a change When a change can be undone, its result includes an `actionLogId`. Ask the client to undo it, or call `aila_undo_action` with that ID. Each change can be undone one time. You can undo your own changes. People who can manage organization settings can also undo changes by others. --- ## Who can do what The connection acts as you. It follows your Aila role and team: - **Calls.** You see the same calls that you see on the Calls page. A team lead sees the team's calls. - **Account setup changes.** Only people who can manage organization settings (for example owners and admins) get the setup change tools. - **Your own settings, charts, and call fixes.** Every member gets these. - **Loan files.** You see the loan files that Aila lets you see in the app. A connection must belong to a current member of the organization to make changes outside loan files. ### Token scopes OAuth tokens and API keys carry scopes. A scope can only **narrow** what your role allows. It never gives more. | Scope | Allows | | :--- | :--- | | `calls:read` | Read calls, contacts, charts, and setup. | | `config:write` | Change account setup. Only people who can manage organization settings get it. | | `me:write` | Change things that belong to you: saved charts, call views, permission mode, call fixes, and invites. | | `loan-files:read` | Read loan files. | | `loan-files:write` | Read and change loan files. | | `offline_access` | Get a refresh token (OAuth only). | Without `config:write` or `me:write`, the connection cannot make changes outside loan files, and `aila_undo_action` is not offered. OAuth discovery (for store reviewers and client implementers): - Protected resource: `https://app.aila.fyi/.well-known/oauth-protected-resource` - Authorization server: `https://app.aila.fyi/.well-known/oauth-authorization-server` ### Token lifetime - An OAuth access token lasts **30 days**. - When the client asks for `offline_access`, Aila also gives a refresh token. ChatGPT asks for it. The refresh token lasts **90 days**. Each refresh gives a new token and turns off the previous one, so the client stays connected without a new sign-in. - To end a connection, go to **Settings > My settings > AI assistants** and click **Disconnect**. Refresh stops at once. --- ## Installation and client setup The ChatGPT, Claude, and Claude Code steps are also in Aila: **Settings > My settings > AI assistants**. ### ChatGPT 1. In ChatGPT, open **Settings > Apps & Connectors > Advanced** and turn on **Developer mode**. 2. Select **Create**. Set the name to `Aila`. 3. Set the URL to `https://app.aila.fyi/api/mcp`. 4. Set authentication to **OAuth**. 5. Sign in to Aila when ChatGPT asks, and approve access. . 3. Set the URL to ### Claude For Claude on the web and Claude Desktop: 1. In Claude, open **Settings > Connectors** and select **Add custom connector**. 2. Set the name to `Aila`. 3. Set the URL to `https://app.aila.fyi/api/mcp`. 4. Select **Connect**. Sign in to Aila when Claude asks, and approve access. Do not select SSE. Do not use `/api/mcp/sse`. . 3. Set the URL to . 4. Select **Connect**. Sign in to Aila when Claude asks, and approve access. Do not select SSE. Do not use ### Claude Code Add the remote HTTP server: ```bash claude mcp add --transport http aila https://app.aila.fyi/api/mcp ``` Then, in Claude Code, run `/mcp`, select **aila**, and sign in. ### Codex Add a streamable HTTP server, then complete OAuth: ```bash codex mcp add aila --url https://app.aila.fyi/api/mcp codex mcp login aila ``` Do not use an SSE URL. ### Cursor 1. Open Cursor **Settings > MCP**. 2. Add a new MCP server (or edit `mcp.json`). 3. Use type **HTTP** / **streamable HTTP**, not SSE. 4. Set the URL to `https://app.aila.fyi/api/mcp`. 5. Complete the Aila OAuth sign-in. Example `mcp.json` entry: ```json { "mcpServers": { "aila": { "url": "https://app.aila.fyi/api/mcp" } } } ``` ### Local stdio (`@withaila/mcp-server`) For local development, run the npm stdio package. This package is **`@withaila/mcp-server`**. It is not `@aila/mcp`. There is no `--org` flag. Set environment variables: - `AILA_API_KEY` (required). Create the key in **Settings > Connections**. - `AILA_BASE_URL` (optional). Default: `https://app.aila.fyi`. Run: ```bash npx -y @withaila/mcp-server ``` Example Cursor / Claude Desktop stdio config: ```json { "mcpServers": { "aila": { "command": "npx", "args": ["-y", "@withaila/mcp-server"], "env": { "AILA_API_KEY": "", "AILA_BASE_URL": "https://app.aila.fyi" } } } } ``` The local stdio server has only six read tools, and it still uses the old names: `list_calls`, `get_call_transcript`, `search_calls`, `get_call_details`, `lookup_contact`, and `get_team_performance`. Use the remote server for charts, setup changes, loan files, and undo. --- ## Connect with an API key instead of OAuth Clients that cannot run OAuth can send an Aila API key as a Bearer token to the same URL. 1. Go to **Settings > Connections > API keys** and create a key. For loan-file tools, give it the **Read Loan Files** and **Write Loan Files** permissions. Copy the key when Aila shows it. It appears only one time. 2. Add the server in your client: ```bash claude mcp add --transport http aila https://app.aila.fyi/api/mcp --header "Authorization: Bearer YOUR_API_KEY" ``` ```json { "mcpServers": { "aila": { "url": "https://app.aila.fyi/api/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` The key acts as the person who created it. A key that is not linked to a current member can read. It can change loan files only, and it cannot use `aila_undo_action`. --- ## Recommended first prompt After you connect: ```text Use Aila. Read my setup status first, then show my calls from this week. Tell me what you will change before you change anything. ``` For loan files: ```text Use Aila. Find the loan file for and list the missing documents. Draft an email to the borrower that asks for them. Do not send it. ``` --- ## Related documentation - [Integrations Overview](https://docs.aila.fyi/integrations): Overview of supported connections. - [Ask Aila](https://docs.aila.fyi/agents/ask-aila): The assistant in the Aila app. It uses most of the same tools. - [API Reference > Authentication](https://docs.aila.fyi/api-reference/authentication): API keys for the local stdio package. - [API Reference > Webhooks](https://docs.aila.fyi/api-reference/webhooks): Real-time event streaming. - [Call setup](https://docs.aila.fyi/settings/call-setup): Manage AI extraction fields in the web app.