# Use Grayson from an AI agent (MCP) (/mcp)



Grayson has a remote MCP server at `https://api.finic.ai/mcp`, using MCP's Streamable HTTP transport. Add it to your AI agent, and the agent can sign you up for Finic, get its own API key once you approve it, and ask Grayson questions about your cases, without you copying keys around.

Once it's added, try a prompt like:

> Set up Grayson (the Finic MCP server) for me and ask it whether this case looks like account takeover: a login from a new device abroad, a password reset, then a $4,900 wire to a new payee six minutes later.

## Add the server [#add-the-server]

<Tabs items="['Claude Code', 'Claude', 'Cursor', 'VS Code', 'Codex', 'Other clients']">
  <Tab value="Claude Code">
    Without a key:

    ```bash
    claude mcp add --transport http grayson https://api.finic.ai/mcp
    ```

    With a key from the `GRAYSON_API_KEY` environment variable (this writes the key into your Claude Code configuration):

    ```bash
    claude mcp add --transport http grayson https://api.finic.ai/mcp --header "Authorization: Bearer $GRAYSON_API_KEY"
    ```

    To share the server with your team without sharing a key, add it to the project's `.mcp.json`, which reads each person's own `GRAYSON_API_KEY`:

    ```json title=".mcp.json"
    {
      "mcpServers": {
        "grayson": {
          "type": "http",
          "url": "https://api.finic.ai/mcp",
          "headers": { "Authorization": "Bearer ${GRAYSON_API_KEY}" }
        }
      }
    }
    ```

    Add `--scope user` to the command to use Grayson in all your projects. See [Claude Code's MCP guide](https://code.claude.com/docs/en/mcp).
  </Tab>

  <Tab value="Claude">
    In Claude (claude.ai, Claude Desktop or Cowork), add a custom connector with the URL `https://api.finic.ai/mcp` and no sign-in. On Pro and Max, open **Customize > Connectors** and choose **Add custom connector**. On Team and Enterprise, an owner adds it under **Organization settings > Connectors**.

    You can add the header `Authorization: Bearer <key>` under the connector's request headers. On Team and Enterprise, everyone who uses the connector shares the headers an owner sets, so don't add a personal key there: leave them empty, and Claude passes each person's key with each call instead. See [Anthropic's guide to custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
  </Tab>

  <Tab value="Cursor">
    In `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project:

    ```json title="mcp.json"
    {
      "mcpServers": {
        "grayson": {
          "url": "https://api.finic.ai/mcp",
          "headers": { "Authorization": "Bearer ${env:GRAYSON_API_KEY}" }
        }
      }
    }
    ```

    Leave out `headers` until you have a key. See [Cursor's MCP docs](https://cursor.com/docs/context/mcp).
  </Tab>

  <Tab value="VS Code">
    In `.vscode/mcp.json`, or your user configuration (**MCP: Open User Configuration**). VS Code asks for the key the first time and stores it securely:

    ```json title=".vscode/mcp.json"
    {
      "inputs": [
        { "type": "promptString", "id": "grayson-api-key", "description": "Grayson API key (gsk_...)", "password": true }
      ],
      "servers": {
        "grayson": {
          "type": "http",
          "url": "https://api.finic.ai/mcp",
          "headers": { "Authorization": "Bearer ${input:grayson-api-key}" }
        }
      }
    }
    ```

    Leave out `inputs` and `headers` until you have a key. See [VS Code's MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
  </Tab>

  <Tab value="Codex">
    Without a key:

    ```bash
    codex mcp add grayson --url https://api.finic.ai/mcp
    ```

    With the key in the `GRAYSON_API_KEY` environment variable:

    ```bash
    codex mcp add grayson --url https://api.finic.ai/mcp --bearer-token-env-var GRAYSON_API_KEY
    ```

    Or in `~/.codex/config.toml`:

    ```toml title="config.toml"
    [mcp_servers.grayson]
    url = "https://api.finic.ai/mcp"
    bearer_token_env_var = "GRAYSON_API_KEY"
    ```

    Codex adds `Bearer ` itself. See [Codex's MCP docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
  </Tab>

  <Tab value="Other clients">
    Any client that supports remote MCP servers over Streamable HTTP works. Give it:

    * **URL:** `https://api.finic.ai/mcp`
    * **Header,** once you have a key: `Authorization: Bearer <key>`

    No OAuth is needed. If your client can't send headers, your agent can pass the key as the `api_key` argument of each call.
  </Tab>
</Tabs>

If you already have an API key, add it as the `Authorization: Bearer <key>` header, as in the examples, and your agent can call `decide` right away. Create keys at [portal.finic.ai/keys](https://portal.finic.ai/keys). Without a key, add the server with just its URL: your agent signs you up first.

## Sign up from your agent [#sign-up-from-your-agent]

When there's no key yet, your agent walks you through getting one:

<Steps>
  <Step>
    ### Your agent sends you a link [#your-agent-sends-you-a-link]

    It calls `sign_up` and shows you a link to open in your browser. The link works for 24 hours.
  </Step>

  <Step>
    ### Create your account and approve the key [#create-your-account-and-approve-the-key]

    The page says which agent asked for a key. Create a Finic account, with email and password or with Google, or sign in to yours. A new account accepts Finic's policies and chooses its data retention.

    Then the page asks whether to give the agent an API key. If you belong to several organizations, pick one. Choose how long the key lasts: 30 days by default, or 1 hour, 1 day, 7 days, 90 days, 1 year or never. Then approve or decline.

    Only approve if you asked your agent to set up Grayson just now.
  </Step>

  <Step>
    ### Tell your agent you're done [#tell-your-agent-youre-done]

    It calls `get_api_key` and receives the key, once. It should store the key securely, for example as the `GRAYSON_API_KEY` environment variable, and add it to its MCP configuration as the `Authorization` header. Until then it can pass the key with each call.
  </Step>
</Steps>

The key appears in the portal under [API keys](https://portal.finic.ai/keys) as "Agent: " followed by the agent's name, created by you. Revoke it there at any time.

### Credit [#credit]

New organizations come with free credit. During the invite-only beta, an organization created from an agent's link starts with $5 of free credit, and the rest of the $25 is added once Finic approves the account. Until then, `get_account` shows it as `pending_credit_usd`. Decisions cost the same as through the API: $0.035 per million input tokens.

## Tools [#tools]

| Tool          | Needs a key | What it does                                                                                                                                                                                                                                                                                                                    |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sign_up`     | No          | Starts a sign-up. Optional inputs: `agent_name` (shown to you on the sign-up page, such as "Claude Code"), `company`, `use_case`. Returns `signup_url` for you to open, `setup_code` for the agent to keep (it's never shown to you), `expires_at` and `next_steps`                                                             |
| `get_api_key` | No          | Takes the `setup_code` and returns a `status`. `ready` comes with `api_key` (returned only once), `key_expires_at`, `organization` and `credit_usd`                                                                                                                                                                             |
| `decide`      | Yes         | Asks Grayson about a case. Inputs: `state` (text, a JSON object or an array), `questions` (the same as in [POST /v1/decide](/reference/decide), including `criteria` and [`base_rate`](/concepts/base-rates)), optional `model` (`grayson-1` by default) and optional `api_key`. Returns the same response as `POST /v1/decide` |
| `get_account` | Yes         | Read-only. Returns `organization`, `credit_usd`, `pending_credit_usd`, `key_name`, `key_expires_at`, `usd_per_million_tokens`, `models` and `add_credit_url`                                                                                                                                                                    |

`get_api_key` returns one of these statuses:

| `status`        | Meaning                                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `pending`       | You haven't approved the key yet                                                                                            |
| `ready`         | Here's the key. It's returned only this once                                                                                |
| `already_taken` | The key was already returned. If it's lost, create a new one in the portal                                                  |
| `declined`      | You declined to give the agent a key                                                                                        |
| `expired`       | The link is more than 24 hours old, or an approved key wasn't taken within 24 hours of approval. Start again with `sign_up` |
| `invalid`       | That isn't a setup code from `sign_up`                                                                                      |

## Authentication [#authentication]

`decide` and `get_account` need a Grayson API key. Send it one of two ways:

* **The `Authorization: Bearer <key>` header,** configured in your MCP client. This is the recommended way.
* **The `api_key` argument** in the tool call. An agent uses it right after `get_api_key`, before its configuration has the key, in clients that can't send headers, and where a connector's headers are shared by a whole organization. When a call has both, the argument is used.

`sign_up` and `get_api_key` need no key.

## Limits, errors and usage [#limits-errors-and-usage]

`decide` goes through the same API as [POST /v1/decide](/reference/decide), so the same [rate limits](/reference/limits), credit, usage and data retention apply, and its decisions appear under Usage in the portal.

An error comes back as an MCP tool error whose text is the error type and message, with the field at fault when there is one. Authentication, credit and rate-limit errors also say what to do next. For example:

```text
invalid_request: A choice's base_rate shares must add up to 1. (questions.claim_type.base_rate)
```

See [Errors](/reference/errors) for every error type. Your agent should call `get_api_key` after you say you've approved the key, not over and over: repeated calls are slowed down.