# Alani Insights MCP server

Alani Insights has an official, hosted, remote MCP server. It gives an AI assistant read and write access to the structured tables in an Insights workspace: contacts, companies, deals, tasks, research records, or any tables a team has defined. People see and edit the same tables in the Alani Insights app. There is nothing to install or host.

| | |
| --- | --- |
| Server URL | `https://mcp.alaniinsights.com/v3` |
| Transport | Streamable HTTP |
| Sign-in | OAuth 2.0 authorization code with PKCE and dynamic client registration, or an API key sent as a bearer token |
| Tools | Seven: four that read, three that write |
| Run by | bundleIQ, the maker of Alani Insights |
| Requires | An Alani Insights account on a paid plan. MCP access is included on every plan. See [pricing](/alani-insights/pricing) |

Everything on this page describes the production server as of 2026-11-21.

## What the server is for

Use it when an assistant, or several assistants, need a shared place to keep structured records that outlast a conversation, and when people need to open and correct those records themselves. Common uses are a CRM the assistant runs, a personal CRM, a research list shared between agents, and tracking for events, hiring, or vendors.

The server reads and writes records. It does not send email, read an inbox, or run on a schedule; the assistant that connects does those with its own tools. The Alani Insights app also has its own built-in assistant and agents, which are separate from this server and are described on the [product overview](/alani-insights).

## Connect

A person needs an Alani Insights workspace first: they sign up at https://alaniinsights.com, create an organization, and choose a plan. If an assistant starts connecting before that, sign-in sends the person to sign up and the connection may need to be started again.

### Claude Code

Tested 2026-11-21 with an API key. The server reported as connected.

```
claude mcp add --transport http alani-insights https://mcp.alaniinsights.com/v3 \
  --header "Authorization: Bearer $ALANI_API_KEY"
```

Without the header, Claude Code uses browser sign-in:

```
claude mcp add --transport http alani-insights https://mcp.alaniinsights.com/v3
```

### Claude apps (claude.ai and Claude Desktop)

Add a custom connector with the server URL. Claude opens a browser window for the person to sign in to Alani Insights and approve access.

### ChatGPT

ChatGPT connects to remote MCP servers through custom connectors that sign in with OAuth, and this server supports OAuth with dynamic client registration. Use the server URL above and browser sign-in; ChatGPT custom connectors use OAuth, not an API key header. According to OpenAI's help documentation as read on 2026-11-21, which ChatGPT plans can add a custom connector, and whether it may write as well as read, depends on the plan and on developer mode. Check OpenAI's current documentation for your plan.

### Other MCP clients

The server follows the MCP specification for remote servers: Streamable HTTP, with OAuth and dynamic client registration, or a custom `Authorization` header. A client that supports those connects with the same server URL.

## Sign-in and permissions

**OAuth.** The server publishes its metadata at `https://mcp.alaniinsights.com/.well-known/oauth-authorization-server` and `https://mcp.alaniinsights.com/.well-known/oauth-protected-resource`. An unauthenticated request receives `401` with a `WWW-Authenticate` header pointing to that metadata. PKCE with `S256` is supported. The scope is `mcp`.

**API key.** A person creates a key in the app at https://alaniinsights.com/mcp and sends it as `Authorization: Bearer <key>`. A key has either full access, or access limited to named tables, with search, create, update, and delete granted separately on each table.

**What an assistant can see.** `list_tables` returns only the tables the connection can reach, each with a `permissions` object: `can_read`, `can_create`, `can_update`, `can_delete`. An operation the connection is not allowed to perform returns `PERMISSION_DENIED`.

Keys should be stored in an environment variable or a secrets manager, never pasted into a chat.

## Tools

All seven were called against the production server on 2026-11-21.

| Tool | Reads or writes | What it does |
| --- | --- | --- |
| `list_tables` | Reads | Lists every table the connection can reach: id, name, `table_name`, description, permissions |
| `describe_table` | Reads | Returns one table's fields: name, type, required flag, written description, allowed values for choice fields, and the filter operators each field type accepts |
| `search_records` | Reads | Returns records, with filters, column selection, aggregates, ordering, `limit`, and `offset` |
| `refresh_tables` | Reads | Reloads the table list after tables or fields have changed |
| `create_record` | Writes | Adds one record |
| `update_record` | Writes | Changes the fields sent on one record, by id. Other fields are left as they are |
| `delete_record` | Writes, cannot be undone | Removes one record by id |

The server does not create or change tables or fields. Those are made in the app, or over the REST API with a full-access key.

### Arguments

```
search_records({
  "table": "people",                  // table_name from list_tables
  "filters": { "status": "active", "last_contacted[lt]": "2026-10-01" },
  "select": "id, name, email",        // columns, or aggregates such as "COUNT(*) AS n"
  "orderBy": "last_contacted",
  "orderDirection": "asc",
  "limit": 20,
  "offset": 0
})

create_record({ "table": "people", "record": { "name": "Ann Lee", "email": "ann@example.com" } })

update_record({ "table": "people", "id": "<record id>", "updates": { "status": "contacted" } })

delete_record({ "table": "people", "id": "<record id>" })
```

**Filters.** An exact match is `"field": value`. Operators are written `"field[operator]": value`. For numbers and dates: `gt`, `gte`, `lt`, `lte`, `neq`. For text: `like` and `ilike`, which match partial text, and `not`. Dates are `YYYY-MM-DD`. Yes or no fields take `true` or `false`.

**Field types.** `text`, `number`, `date`, `boolean`, `enum` (a fixed list of choices), `uuid`, and `foreign-key` (a link to a record in another table).

**Validation.** A record missing a required field, or with a choice value that is not on the list, is rejected with `VALIDATION_ERROR`. The error names the problem, lists the allowed values for a choice field, and includes the expected schema.

**Errors.** `VALIDATION_ERROR`, `UNKNOWN_TABLE` (includes the list of available tables), `PERMISSION_DENIED`, and `INTERNAL_ERROR`.

## Working guidance

- **Pass a `limit` and a `select` on every search**, so the assistant fetches only the rows and columns it needs.
- **Read the schema first.** Call `describe_table` and use the field names and choices it returns in filters, selections, and writes.
- **Look a record up before creating it.** Search by an exact match on a key such as an email or domain, and create the record only if nothing comes back.
- **Update by id, and send only the fields you mean to change.** Other fields are left as they are.
- **For totals by group, use the REST API**, which supports grouping. Over MCP, run one filtered aggregate per group.
- **When several assistants share a table, give each new item one writer**, and give each role its own fields to update.
- **Send dates as `YYYY-MM-DD`.**
- **Records, not files.** Keep documents and images where they are and record their status or location.

## Examples

**An assistant-run CRM.** With a contacts table, a deals table, and an activities table:

```
// Who is due a follow-up?
search_records({
  "table": "activities",
  "filters": { "kind": "task", "done": false, "on_date[lte]": "2026-11-21" },
  "select": "id, subject, person, on_date",
  "orderBy": "on_date",
  "limit": 25
})

// How many open deals are at the proposal stage, and what are they worth?
search_records({
  "table": "deals",
  "filters": { "stage": "proposal" },
  "select": "COUNT(*) AS deals, SUM(amount) AS total"
})
```

**Several agents sharing records.** Look a record up by an exact key before adding it, and give one writer responsibility for each new item:

```
search_records({ "table": "companies", "filters": { "domain": "example.com" }, "select": "id", "limit": 1 })
// only if nothing came back:
create_record({ "table": "companies", "record": { "name": "Example Co", "domain": "example.com", "status": "found" } })
```

Runnable versions of both, with sample data, are in the public examples repository: https://github.com/bundleIQ/alani-insights-examples

A recorded run with screenshots, in which two separate assistants work from the same records with corrections entered in the app in between, is in the same repository: https://github.com/bundleIQ/alani-insights-examples/tree/main/examples/shared-records-walkthrough

## REST API

The same tables are available over REST at `https://api.alaniinsights.com/v1`, with the key sent as `x-api-key`. REST can also create tables and fields, group results, and count without fetching. Endpoints, query parameters, and safe-write rules are in the [technical reference for agents](/alani-insights/agents/reference).

## Related

- [Pricing: what each plan includes](/alani-insights/pricing)
- [For AI agents: deciding whether Insights fits, and setting it up](/alani-insights/agents)
- [Worked example: an agent-run CRM](/alani-insights/agents/crm)
- This page as Markdown: https://www.bundleiq.com/alani-insights/mcp-server.md

Support: hello@bundleiq.com
