# Connect your AI assistant

> Create an API key and connect Claude or another MCP client to EDOS, so your assistant can read and update your contacts, projects, notes, tasks and tags.

## Before you start

- Your account needs API access. Incenti turns it on per account; if you see no
  **API keys** section on your profile's **Settings** tab, ask Incenti support.
- An API key acts as you. Your assistant sees and changes only what you can in the
  Incenti Portal, and never more than the permissions you give the key.
- You need an AI assistant that supports the Model Context Protocol (MCP) with a
  custom header, such as Claude Code or Claude Desktop. Connectors that require an
  OAuth sign-in, such as ChatGPT connectors, are not supported yet.

## Create an API key

1. Open the user menu at the bottom of the sidebar and choose **Profile**.
2. Open the **Settings** tab and find **API keys**.
3. Select **Create API key**.
4. Enter a **Name** that says where the key will be used, such as "Claude Desktop".
5. Under **Permissions**, choose **Read only** to let the assistant look things up, or
   **Read and write** to let it also create and update records. **Advanced** lets you
   pick areas one by one.
6. Optionally set **Expires**, the last day the key works.
7. Select **Create key**, then copy the key. It starts with `inc_live_` and is shown
   only this once. Keep it as safe as a password: anyone with it can act as you,
   within its permissions.

## Connect Claude Code

Run this in a terminal, with your key in place of `inc_live_…`:

```bash
claude mcp add --transport http incenti https://api.incenti.co/mcp \
  --header "Authorization: Bearer inc_live_…"
```

Start Claude Code and run `/mcp` to check that **incenti** shows as connected.

## Connect another MCP client

Add a server with these settings:

| Setting   | Value                                         |
| --------- | --------------------------------------------- |
| Transport | Streamable HTTP                               |
| URL       | `https://api.incenti.co/mcp`                  |
| Header    | `Authorization: Bearer inc_live_…` (your key) |

Incenti has tested Claude Code and the MCP Inspector. Other clients that send a custom
header to a Streamable HTTP server should work the same way.

## What your assistant can do

Reading uses three tools that work across record types:

| Tool                    | What it does                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| `describe_record_types` | Lists what the key can read and the filters for each                                              |
| `find_records`          | Lists contacts, organizations, projects, pipelines, notes, tags, tasks or users, a page at a time |
| `get_record`            | Reads one contact, organization, project or task in full                                          |

Writing uses one tool per action. Creating and updating take a list of up to 25
records in one call: `create_contacts`, `update_contacts`, `create_organizations`,
`update_organizations`, `create_projects`, `update_projects`, `create_notes`,
`update_notes`, `create_tags`, `create_tasks` and `update_tasks`. Each record in the
list is saved on its own, so if one fails (for example a missing required field) the
others are still saved, and your assistant is told which one failed and why. Other
actions work on one record at a time: `move_project_stage`, `complete_task`, and
`set_contact_tags`, `set_organization_tags` and `set_project_tags`. Nothing can be
deleted through the API.

The tools your assistant sees depend on the key's permissions and the modules your
account has. A **Read only** key shows no tools that write.

## What happens next

- Changes made through your key appear in the activity feed under your name, and
  notify people exactly as the same change in the Incenti Portal does. The audit log
  records that the change came through your API key.
- The key's **Last used** date updates as your assistant uses it.
- A key unused for 180 days is revoked automatically, and you get a notification.
- Each key may make 120 requests a minute, of which 30 changes, and your account
  600 a minute across all keys. Each record in a list counts as one change. Over the limit, the assistant is asked to wait a
  minute and try again.

## Common questions

**Q: My assistant says the API key is missing, invalid, revoked or expired.**
A: Check that the header is exactly `Authorization: Bearer ` followed by the whole key,
and that the key is still listed as active under **API keys**. A revoked or expired key
cannot be turned back on; create a new one.

**Q: My assistant says "API access is not enabled for this account".**
A: Your account's API access was turned off. Ask Incenti support.

**Q: My assistant says the key lacks a permission.**
A: The key was created without that area, for example a **Read only** key asked to
create a contact. Create a new key with the permissions you need and replace the old one.

**Q: How do I stop my assistant from using Incenti?**
A: Select **Revoke** next to the key under **API keys**. It stops working within a
minute. An account **Admin** can also revoke any key in the account from the account's
**Settings** tab.

**Q: Can my assistant be tricked by text stored in a record?**
A: Incenti returns record contents to the assistant as data and tells it to treat them
as data, never as instructions. Still review what your assistant proposes to change,
especially when it acts on notes written by other people.

## Related

- [Roles and permissions](https://kb.incenti.co/getting-started/roles-and-permissions.md)
- [AI assistants in EDOS and Insights](https://kb.incenti.co/getting-started/ai-assistants.md)
