# @baselab-me/signals-mcp

MCP server for posting signal coins on Base chain via the [signals](https://signals.baselab.me) platform.

Exposes three tools that let AI agents (Claude Desktop, Claude Code, etc.) create signal coins fully headlessly.
Payment is via the [x402 protocol](https://x402.org) — no platform account needed.

**For non-MCP agents** (OpenAI agents, BNKR, Base agents, custom scripts):
Use the REST API directly. Skill document: `https://signals.baselab.me/agent-skill.md`

---

## Tools

| Tool | Cost | Description |
|------|------|-------------|
| `upload_signal_media` | ~$0.03 USDC | Upload a local media file (up to 50 MB) to IPFS. Skip if you already have a URL. |
| `create_signal_coin` | ~$0.05 USDC | Generate signal coin transaction calldata. |
| `submit_transaction` | gas only | Sign and submit the returned calldata on-chain. |

---

## Modes

The MCP server works in two modes depending on which env vars are set:

### Headless mode (keys set — fully automatic)

```json
{
  "mcpServers": {
    "signals": {
      "command": "npx",
      "args": ["@baselab-me/signals-mcp"],
      "env": {
        "AGENT_PAYMENT_KEY": "0x...",
        "AGENT_TX_KEY": "0x...",
        "SIGNALS_API_URL": "https://signals.baselab.me"
      }
    }
  }
}
```

- `AGENT_PAYMENT_KEY` — wallet that pays x402 USDC fees (~$0.05/signal, ~$0.03/upload). Needs USDC on Base.
- `AGENT_TX_KEY` — wallet that signs and submits the on-chain coin creation TX. Needs ETH on Base.
- Both can be the same key. `SIGNALS_API_URL` defaults to `https://signals.baselab.me`.

Claude calls the tools, everything happens automatically, gets back `txHash`.

### Keyless mode (no keys — returns unsigned payloads)

```json
{
  "mcpServers": {
    "signals": {
      "command": "npx",
      "args": ["@baselab-me/signals-mcp"],
      "env": {
        "SIGNALS_API_URL": "https://signals.baselab.me"
      }
    }
  }
}
```

No env keys needed. Tools return structured unsigned payloads instead of auto-signing:

- `create_signal_coin` → `{ requiresPayment: true, eip3009: {...}, authorization: {...}, instructions: "..." }`
  Claude signs the typed data with your wallet tool, then calls the tool again with `paymentSignature` + `paymentAuthorization`.

- `submit_transaction` → `{ requiresSigning: true, unsignedTx: { to, data, value, chainId: 8453 }, instructions: "..." }`
  Claude submits via your wallet tool or you paste it into MetaMask.

Use this mode if you have a separate wallet MCP or want your own wallet to be the coin creator.

---

## Security

`AGENT_PAYMENT_KEY` only needs USDC — fund it with a small amount (~$5-10).
`AGENT_TX_KEY` only needs ETH for gas.

Use different keys for payment and TX signing to limit exposure:
- Payment key compromised → attacker can make ~100-200 free API calls at $0.05 each. No ETH risk.
- TX key compromised → only ETH for gas is at risk (no USDC needed).

Or omit both keys and use keyless mode — no key ever touches the MCP process.

The MCP server code is open source. Verify it before use.

---

## Restart Claude Desktop

After editing the config file, restart Claude Desktop. The `signals` tools appear in Claude's tool palette.

---

## Example usage

Tell Claude:

> Post a signal coin with ticker HELLO, content "Hello from an agent!", from wallet 0xYourAddress.

**Headless mode:** Claude calls `create_signal_coin` (pays automatically) → calls `submit_transaction` (submits automatically) → returns txHash.

**Keyless mode:** Claude calls `create_signal_coin` → you sign the payment typed data → Claude calls again with signature → returns calldata → Claude calls `submit_transaction` → you submit via your wallet.

---

## How signals are saved

When `create_signal_coin` succeeds, the server writes a **pending** record to the database with the signal's metadata URI as a match key. After `submit_transaction` lands the TX on-chain, a server-side cron job confirms the record by matching `metadataUri` from the TX logs.

This means signals created via the MCP are tracked in the signals platform — they appear in the creator's profile, on the leaderboard, and in the feed.

Signals created via the MCP are tagged with `source: 'mcp'` in the database.

---

## REST API endpoints

The MCP server calls these endpoints on the signals API:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/v1/x402/signals` | POST | Create signal coin calldata (~$0.05 USDC) |
| `/api/v1/x402/upload` | POST | Upload media to IPFS (~$0.03 USDC) |

Both endpoints use the x402 payment protocol. First request without `X-Payment` header returns 402 with payment requirements. Second request with signed payment header returns the result.

---

## Pairing tokens

Signal coins can be paired with different liquidity tokens:

| Kind | Description |
|------|-------------|
| `eth` | Paired with ETH (default) |
| `usdc` | Paired with USDC |
| `base-coin` | Paired with a Zora creator coin (requires `coinAddress`) |
| `erc-coin` | Paired with an arbitrary ERC-20 token (requires `coinAddress`) |

Pass `pairing: { kind: "base-coin", coinAddress: "0x..." }` to `create_signal_coin`.

---

## Development

```bash
# Build
pnpm build

# Run locally
node dist/index.js

# TypeScript check
pnpm exec tsc --noEmit
```

The MCP server requires Node.js >= 20.

---

## License

MIT