Configuration - Pacifica

The MCP server is configured entirely through environment variables passed in your MCP client’s config.
Which keys you provide determines the mode the server runs in.

Environment Variables

Variable	Required	Description
`ADDRESS`	yes	Public address the actions apply to, your main account or a subaccount. Sent as the `account` field.
`PRIVATE_KEY`	no	Base58 Solana secret key (Ed25519) of the main account. Signs POST requests when no agent key is set.
`AGENT_PRIVATE_KEY`	no	Base58 secret key of an API agent wallet (revocable). When set, signs POST requests and sends `agent_wallet`, so you never expose your main key. The agent must already be bound to `ADDRESS`. Takes precedence over `PRIVATE_KEY`.
`AGENT_WALLET`	no	Agent wallet public key. Defaults to the value derived from `AGENT_PRIVATE_KEY`; only set this to override.
`PACIFICA_BASE_URL`	no	API host. Defaults to testnet `https://test-api.pacifica.fi`. Set to `https://api.pacifica.fi` for production.
`SOLANA_RPC_URL`	no	Solana RPC endpoint used by the on-chain funding tools (`mintUsdp`, `depositUsdp`). Defaults to public devnet `https://api.devnet.solana.com`; set a dedicated RPC to avoid public rate limits.
`PACIFICA_PROGRAM_ID`	no	Override the Pacifica on-chain program id used by `depositUsdp`. Defaults per network: the shipped testnet program on testnet, the Pacifica mainnet program on mainnet.
`PACIFICA_USDC_MINT`	no	Override the collateral mint used by `depositUsdp`. Defaults per network: testnet USDP on testnet, Circle USDC on mainnet.

Modes

The server picks a mode from the keys you provide:

Read-only: set only ADDRESS. All read (GET) tools work; write (POST) tools return a clear “read-only mode” error.
Agent-key (recommended): set ADDRESS + AGENT_PRIVATE_KEY. Full trading without ever putting your main wallet’s private key in the config.
Main-key: set ADDRESS + PRIVATE_KEY. Full trading, signing with the main wallet key (legacy behavior).

On startup the server logs the active account and mode to stderr (visible in the MCP logs), e.g. [pacifica-mcp] account=<address> mode=agent-key.

On-Chain Funding Tools

Two tools - mintUsdp and depositUsdp - sign and send Solana transactions directly instead of calling the REST API, so they have their own requirements:

They require PRIVATE_KEY. An agent key signs API requests only and cannot sign on-chain transactions, so it does not work for these tools - this is the one case where the main key is required.
They use SOLANA_RPC_URL for the Solana connection. It defaults to public devnet; set a dedicated RPC to avoid rate limits.
mintUsdp is testnet only and is registered only when PACIFICA_BASE_URL targets testnet. depositUsdp works on both networks; on mainnet it moves real USDC.

On testnet, a typical flow is mintUsdp to credit your wallet, then depositUsdp to move those funds into your exchange balance. See Tools for the tool list.

Recommended: Agent Key

An agent key is a revocable key bound to your account: it can trade, but it cannot move funds the way your main wallet can, and you can revoke it at any time.
Generate and bind one once at app.pacifica.fi/apikey. You sign the binding in-browser, so your main secret never leaves your wallet.
Then configure the MCP with only your account address and the agent key:

{
  "mcpServers": {
    "pacifica": {
      "command": "npx",
      "args": ["-y", "@pacifica-fi/mcp-server"],
      "env": {
        "ADDRESS": "<your Solana account address>",
        "AGENT_PRIVATE_KEY": "<your base58 agent wallet secret key>"
      }
    }
  }
}

For more on how agent keys work in Pacifica’s signing scheme, see API Agent Keys.

Security

Important: Never commit or paste your PRIVATE_KEY or AGENT_PRIVATE_KEY anywhere public. Treat any key that has been exposed as compromised and rotate it.

Prefer an agent key over your main key: it is revocable and limited in scope.
The config file holds your key in plaintext, so protect it like any other secret.

​Environment Variables

​Modes

​On-Chain Funding Tools

​Recommended: Agent Key

​Security

Environment Variables

Modes

On-Chain Funding Tools

Recommended: Agent Key

Security