Use Grayson from an AI agent (MCP)
Add the Grayson MCP server to Claude Code, Cursor, VS Code, Codex or any MCP client. Your agent can sign you up, get an API key with your approval and make decisions.
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
Without a key:
claude mcp add --transport http grayson https://api.finic.ai/mcpWith a key from the GRAYSON_API_KEY environment variable (this writes the key into your Claude Code configuration):
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:
{
"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.
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. Without a key, add the server with just its URL: your agent signs you up first.
Sign up from your agent
When there's no key yet, your agent walks you through getting one:
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.
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.
Tell your agent you're 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.
The key appears in the portal under API keys as "Agent: " followed by the agent's name, created by you. Revoke it there at any time.
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
| 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, including criteria and base_rate), 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
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_keyargument in the tool call. An agent uses it right afterget_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
decide goes through the same API as POST /v1/decide, so the same rate 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:
invalid_request: A choice's base_rate shares must add up to 1. (questions.claim_type.base_rate)See 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.