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

# SDK Setup

> Install and configure the Payo SDK

## Installation

Install the Payo SDK in your MCP server project:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @payo/mcp
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @payo/mcp
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @payo/mcp
    ```
  </Tab>
</Tabs>

## Requirements

* Node.js 18+
* `@modelcontextprotocol/sdk` (peer dependency)
* A Payo provider API key

## Basic Setup

Import `withPayments` and wrap your MCP server:

```typescript server.ts theme={null}
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { withPayments } from '@payo/mcp';

// 1. Create your MCP server
const server = new McpServer({
  name: 'my-api',
  version: '1.0.0'
});

// 2. Wrap with payments
const paidServer = withPayments(server, {
  apiKey: process.env.PAYO_API_KEY!,
  pricing: {
    'tool_a': 0.01,
    'tool_b': 0.05,
  }
});

// 3. Register tools (same as before)
paidServer.tool('tool_a', { /* schema */ }, async (args) => {
  // Implementation
});

// 4. Connect transport
paidServer.connect(transport);
```

## How It Works

`withPayments()` returns your server with payment logic injected:

1. **Intercepts tool registration** - Wraps your tool handlers
2. **Checks pricing on each call** - Looks up the tool's price
3. **Charges before execution** - Calls Payo API for paid tools
4. **Executes your handler** - Only after successful charge

Your tool code doesn't change at all.

## Environment Variables

Set your API key as an environment variable:

```bash theme={null}
# Development
export PAYO_API_KEY=sk_live_your_key_here

# Or in .env file
PAYO_API_KEY=sk_live_your_key_here
```

<Warning>
  Never commit your API key to version control. Use environment variables or secrets management.
</Warning>

## Production Deployment

### Vercel

```json vercel.json theme={null}
{
  "env": {
    "PAYO_API_KEY": "@payo-api-key"
  }
}
```

Add the secret via Vercel dashboard or CLI:

```bash theme={null}
vercel secrets add payo-api-key sk_live_xxx
```

### Railway

Add environment variable in your Railway dashboard under **Variables**.

### Docker

```dockerfile Dockerfile theme={null}
ENV PAYO_API_KEY=""
```

Pass at runtime:

```bash theme={null}
docker run -e PAYO_API_KEY=sk_live_xxx my-mcp-server
```

## TypeScript Support

The SDK is fully typed. Import types if needed:

```typescript theme={null}
import {
  withPayments,
  PaymentConfig,
  PricingConfig,
  PaymentError,
  PaymentErrorCode
} from '@payo/mcp';

const config: PaymentConfig = {
  apiKey: process.env.PAYO_API_KEY!,
  pricing: {
    'my_tool': 0.01
  }
};
```

## Verifying Setup

Test your integration:

1. **Start your server locally**
   ```bash theme={null}
   PAYO_API_KEY=sk_live_xxx node server.js
   ```

2. **Call a tool without a token**
   You should see a `TOKEN_MISSING` error (expected behavior)

3. **Call with a valid agent token**
   Set `AGENT_TOKEN` in your test client. The tool should execute and you should see a charge in your dashboard.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Cannot find module @payo/mcp'">
    Ensure you've installed the package:

    ```bash theme={null}
    npm install @payo/mcp
    ```
  </Accordion>

  <Accordion title="'apiKey is required'">
    The SDK requires an API key. Check:

    * `PAYO_API_KEY` environment variable is set
    * You're reading it correctly: `process.env.PAYO_API_KEY`
  </Accordion>

  <Accordion title="Charges not appearing in dashboard">
    * Verify the API key is a provider key (not agent)
    * Check you're calling paid tools (not free ones)
    * Ensure the agent token is valid
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Setting Prices" icon="dollar-sign" href="/guides/provider/pricing">
    How to set and update prices
  </Card>

  <Card title="Configuration" icon="gear" href="/sdk/configuration">
    All SDK options
  </Card>
</CardGroup>