> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avina.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Avina to Claude or Codex (MCP)

> Give Claude or Codex live, secure access to your Avina workspace over the Model Context Protocol.

Avina exposes a hosted **[Model Context Protocol](https://modelcontextprotocol.io) (MCP)** server so you can ask **Claude or Codex** to read your accounts, contacts, and signals and to drive your signal workflows — all scoped to your workspace, in natural language.

Once connected, you can ask your AI assistant things like:

* *"What alerts fired for my top accounts this week?"*
* *"Draft a new-hire signal for VPs of Sales at Series B SaaS companies."*
* *"Generate more leads for my champion-movement signal, then turn on daily monitoring."*

<Info>
  **Endpoint:** `https://api.avina.io/mcp` · **Transport:** Streamable HTTP · **Auth:** OAuth (Avina / WorkOS login — no API keys to copy)
</Info>

<Note>
  You sign in with your normal Avina login. Claude or Codex only sees the workspace you're a member of.
</Note>

***

## Before you start

* An active **Avina workspace** and login. If you can sign in at [app.avina.io](https://app.avina.io), you're set.
* **For Codex:** access to Plugins in the Codex app.
* **For Claude:** a plan that supports custom connectors — Free, Pro, Max, Team, and Enterprise all qualify. On Team / Enterprise, custom connectors may be gated by your workspace owner.

***

## Connect in Codex

<Steps>
  <Step title="Open Plugins">
    In Codex, open **Plugins**.
  </Step>

  <Step title="Open MCP">
    Select **MCP** from the Plugins screen.
  </Step>

  <Step title="Add Avina">
    Click **Add Avina**, then follow the prompts to add the Avina MCP server.
  </Step>

  <Step title="Sign in to Avina">
    Complete the Avina / WorkOS login in your browser and approve access. When you return to Codex, Avina is ready to use.
  </Step>
</Steps>

Start a task and ask Codex to use Avina, for example: *"Using Avina, show me the highest-fit accounts with signals this week."*

***

## Connect on claude.ai

<Steps>
  <Step title="Open Connectors">
    Go to **Settings → Connectors** (also reachable via **Customize → Connectors**).
  </Step>

  <Step title="Add a custom connector">
    Click **Add custom connector**.
  </Step>

  <Step title="Enter the Avina MCP URL">
    Paste the server URL and give it a name:

    | Field                     | Value                      |
    | ------------------------- | -------------------------- |
    | **Name**                  | `Avina`                    |
    | **Remote MCP server URL** | `https://api.avina.io/mcp` |

    Leave the **Advanced settings** (OAuth Client ID / Secret) blank — Avina handles the OAuth handshake automatically. Click **Add**.
  </Step>

  <Step title="Sign in to Avina">
    Click **Connect** on the new **Avina** connector. A browser window opens for your Avina / WorkOS login. Approve access, and you'll be returned to Claude with the connector marked **Connected**.
  </Step>

  <Step title="Enable it in a chat">
    In any conversation, click the **+** button, choose **Connectors**, and toggle **Avina** on. Claude can now call your workspace.
  </Step>
</Steps>

***

## Connect in Claude Cowork

Claude Cowork uses the same custom-connector system as claude.ai.

<Steps>
  <Step title="Open Connectors">
    In Cowork, open **Settings → Connectors**.
  </Step>

  <Step title="Add the Avina connector">
    Choose **Add custom connector**, then enter:

    | Field                     | Value                      |
    | ------------------------- | -------------------------- |
    | **Name**                  | `Avina`                    |
    | **Remote MCP server URL** | `https://api.avina.io/mcp` |

    Click **Add**, then **Connect** and complete the Avina login in your browser.
  </Step>

  <Step title="Use it">
    Reference the connector in your task, e.g. *"Using Avina, list this week's champion-movement alerts and draft outreach for the top three."* Cowork will call the tools it needs and ask before running any action that changes your data.
  </Step>
</Steps>

***

## What Claude and Codex can do

Once connected, Claude or Codex has access to the following tools, all scoped to your workspace:

| Tool                       | What it does                                                                            | Access |
| -------------------------- | --------------------------------------------------------------------------------------- | ------ |
| `whoami`                   | Confirms which user and workspace you're connected as                                   | Read   |
| `describe_schema`          | Lists the filterable and groupable fields available to the query tools                  | Read   |
| `query_accounts`           | Find, count, or aggregate accounts (companies)                                          | Read   |
| `query_contacts`           | Find, count, or aggregate contacts (people)                                             | Read   |
| `query_signals`            | Query the leads a configured signal surfaced — what triggered, ranked by ICP fit        | Read   |
| `list_signals`             | List your configured signal definitions and their active state                          | Read   |
| `draft_signal`             | Turn a plain-English description into a draft signal (created inactive for your review) | Write  |
| `request_more_leads`       | Generate more leads / the audience for a signal                                         | Write  |
| `signal_generation_status` | Check whether a `request_more_leads` run has finished                                   | Read   |
| `update_signal`            | Update a signal's configuration and filters                                             | Write  |
| `monitor_signal`           | Turn on daily monitoring for a signal                                                   | Write  |
| `stop_monitoring`          | Turn off monitoring for a signal                                                        | Write  |

<Note>
  **Read** tools never modify your data. **Write** tools change signals in your workspace — your AI assistant will summarize what it's about to do and may ask for confirmation before acting. New signals from `draft_signal` are always created **inactive** so nothing goes live without your say-so.
</Note>

***

## Security & access

* **You sign in as you.** Authentication runs through Avina's standard WorkOS login (OAuth 2.0). No API keys or secrets are pasted into your AI assistant or stored in a config file.
* **Workspace-scoped.** Claude or Codex can only see and act on the workspace you're a member of. If you belong to more than one, the connector uses the workspace tied to your session.
* **Least privilege.** Every request is authorized against your existing Avina role, and write tools funnel through a server-side allowlist — the assistant can only set the fields Avina explicitly permits.
* **Revoke anytime.** Remove Avina under **Plugins → MCP** in Codex, or disconnect it under **Settings → Connectors** in Claude, to immediately cut off access.

### Team & Enterprise workspaces

On Team and Enterprise plans, a workspace **owner** adds the connector once so members can enable it:

1. Go to **Organization settings → Connectors**.
2. Click **Add**, hover **Custom**, and choose **Web**.
3. Enter the server URL `https://api.avina.io/mcp` and click **Add**.
4. Members then open **Settings → Connectors** and click **Connect** on the **Avina** connector to sign in with their own Avina login.

***

## Troubleshooting

| Symptom                                                            | Fix                                                                                                                                                                       |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Avina isn't shown in Codex**                                     | Open **Plugins → MCP** and choose **Add Avina**. If Plugins isn't available, update Codex and ask your workspace admin whether plugins are enabled.                       |
| **"Add custom connector" isn't shown**                             | On Team/Enterprise, your owner must enable custom connectors first. On individual plans, confirm you're on a supported plan.                                              |
| **Login window doesn't return / connection stays "Not connected"** | Complete the Avina sign-in fully in the popup, and allow pop-ups for claude.ai. Then click **Connect** again.                                                             |
| **The assistant says it can't reach the tools**                    | In Claude, make sure the connector is toggled **on** for that conversation via the **+ → Connectors** menu. In Codex, confirm Avina is connected under **Plugins → MCP**. |
| **"Ambiguous workspace" or wrong workspace**                       | You likely belong to multiple workspaces. Contact **[support@avina.io](mailto:support@avina.io)** to confirm which workspace your login resolves to.                      |

Still stuck? Email **[support@avina.io](mailto:support@avina.io)** and we'll help you get connected.