MCP

Connect an agent to Livy through the protected MCP runtime endpoint.

Overview

The Model Context Protocol (MCP) lets AI clients call external tools. Livy exposes a project-scoped MCP server that agents use to request protected Solana actions.

Use the endpoint shown in MCP Setup:

https://api.livylabs.xyz/api/v1/tenants/<tenant-id>/projects/<project-id>/mcp?integration_id=<integration-id>

The endpoint is authenticated with a scoped runtime API key:

Authorization: Bearer $LIVY_API_KEY

This is the path that creates Livy requests, guardrail decisions, approval nonces, execution state, and receipts. Direct wallet sends are not protected Livy actions and will not appear in Livy request history.

Setup

Before connecting

In the Livy dashboard:

1. Create or select the project that owns the agent runtime.
2. Register an active agent wallet profile.
3. Create an active guardrail for the action type, network, wallet, and asset.
4. Open MCP Setup and create a runtime API key.
5. Copy the MCP endpoint and store the API key in the agent runtime environment.

Use these environment variables in local tools:

export LIVY_API_KEY="<runtime-api-key>"
export LIVY_MCP_ENDPOINT="<mcp-endpoint-from-dashboard>"
export LIVY_WALLET_ID="<wallet-id-from-dashboard>"

The API key secret is shown once. Do not put it in browser code, public repos, prompts, or local skill files.

Claude Code

Add Livy as a remote HTTP MCP server:

claude mcp add --transport http livy "$LIVY_MCP_ENDPOINT" \
  --header "Authorization: Bearer $LIVY_API_KEY"

Verify the server is configured:

claude mcp get livy

Inside Claude Code, ask for an action that should use Livy, such as:

List the protected Livy actions for my wallet.

Claude Code can send the required bearer header. Use this path when you want a hosted Livy MCP server without installing a local proxy.

Cursor

Create or edit .cursor/mcp.json in the project, or ~/.cursor/mcp.json for a global setup:

{
  "mcpServers": {
    "livy": {
      "url": "${env:LIVY_MCP_ENDPOINT}",
      "headers": {
        "Authorization": "Bearer ${env:LIVY_API_KEY}"
      }
    }
  }
}

Reload Cursor after saving the config. Keep LIVY_API_KEY in the shell environment rather than hardcoding it in the JSON file.

Windsurf and other MCP clients

Use Livy with clients that support remote HTTP MCP servers and custom headers.

Most clients use the same shape:

{
  "mcpServers": {
    "livy": {
      "serverUrl": "https://api.livylabs.xyz/api/v1/tenants/<tenant-id>/projects/<project-id>/mcp?integration_id=<integration-id>",
      "headers": {
        "Authorization": "Bearer ${env:LIVY_API_KEY}"
      }
    }
  }
}

Some clients call the URL field url instead of serverUrl. Use the field your client documents, but keep the same endpoint and Authorization header.

Claude.ai and Claude Desktop

Livy currently uses runtime API keys for MCP auth. Claude.ai and Claude Desktop custom connectors are best suited to OAuth-backed remote MCP servers, and user-pasted static bearer tokens are not the right path for that hosted connector flow.

For Claude today, use Claude Code with the bearer header setup above. If you need Claude.ai or Claude Desktop custom connector support, the Livy MCP server must expose an OAuth connector flow before those surfaces can connect cleanly.

Livy CLI

The Livy agent package is published as @livylabs/ai. It includes the livy-ai CLI for local agent setup, protected MCP runs, and SDK helpers for product code.

For pnpm projects, install it as a project dependency when the agent runtime or app code imports the SDK:

pnpm add @livylabs/ai
pnpm exec livy-ai keypair init --output .livy/agent-keypair.json
export LIVY_AGENT_KEYPAIR="$(pwd)/.livy/agent-keypair.json"

For one-off CLI checks, run the published package without adding it to the project:

pnpm dlx @livylabs/ai mcp run \
  --endpoint "$LIVY_MCP_ENDPOINT" \
  --api-key "$LIVY_API_KEY" \
  --wallet-id "$LIVY_WALLET_ID" \
  --action-type solana.native_transfer \
  --intent "Authorize only: check this transfer against Livy guardrails" \
  --destination <destination-public-key> \
  --amount-atomic <lamports> \
  --agent-keypair "$LIVY_AGENT_KEYPAIR" \
  --authorize-only

After installation, run a protected MCP flow from the project:

pnpm exec livy-ai mcp run \
  --endpoint "$LIVY_MCP_ENDPOINT" \
  --api-key "$LIVY_API_KEY" \
  --wallet-id "$LIVY_WALLET_ID" \
  --action-type solana.native_transfer \
  --intent "Send the approved devnet SOL transfer" \
  --destination <destination-public-key> \
  --amount-atomic <lamports> \
  --agent-keypair "$LIVY_AGENT_KEYPAIR"

Use --authorize-only for a dry policy check. It does not execute a transfer.

Available tools

The server exposes six tools for protected actions.

Discovery

Authorization

Execution

Status

Required tool order

Protected actions should use this order:

livy_list_actions
livy_prepare_action
livy_authorize_action
livy_get_execution_plan
livy_execute_approved_action
livy_get_request_status

The agent should report success only after Livy returns a request hash and receipt status. Solana confirmation alone is not enough.

Authentication

Use a runtime API key created in MCP Setup. Runtime keys are scoped to the tenant, project, and integration the endpoint belongs to.

Do not use:

• dashboard admin credentials
• private wallet keys
• service admin tokens
• query-string API keys
• keys copied into prompts or public skill files

Troubleshooting

The client cannot connect. Confirm the endpoint starts with https://api.livylabs.xyz and keeps the tenant, project, and integration_id values copied from MCP Setup.

The server returns 401. Create a fresh runtime API key from the same dashboard project and send it as Authorization: Bearer $LIVY_API_KEY.

No tools appear in the client. Confirm the client supports remote HTTP MCP servers. If it requires serverUrl instead of url, rename that field in the config.

livy_list_actions returns no usable action. Create or activate a wallet profile and guardrail for the requested action type, network, wallet, and asset.

Authorization is blocked. Review the guardrail cap, destination, asset or mint, signer, quote freshness, evidence, and network. Change the request or the guardrail instead of bypassing Livy.

Execution fails after approval. Fetch livy_get_execution_plan, build the transaction from that exact plan, sign it with the agent keypair, and call livy_execute_approved_action with the returned requestHash.

The action succeeded on Solana but is missing in Livy. The agent likely sent a direct wallet transaction. That path is unprotected and does not create Livy request, decision, approval nonce, execution, or receipt state.

Resources

• Livy App to create wallet profiles, guardrails, runtime keys, and MCP endpoints.
• Quickstart to configure the first protected action path.
• Agent Wallet for wallet matching rules.
• Guardrails for policy checks and decision outcomes.
• Skills for agent instructions that keep protected actions on the MCP path.
• Security & Privacy for runtime key and direct-send guidance.

Read Next

• Agent Wallet
• Guardrails
• Skills