MCP Integration Guide

Prerequisites

Before starting, make sure your environment meets these requirements:

• BirdSafe extension installed, logged in, with MCP text sync enabled.
• You have generated an MCP Key (format: mcp_sk_xxx).
• Node.js 18+ and npm installed on your machine.

1) Install MCP Service

Run the following commands in your BirdSafe project root:

npx birdsafe-mcp-service@latest connect --key mcp_sk_xxx

2) Initialize Key

Recommended interactive init (saves config locally):

birdsafe-mcp-service connect --key mcp_sk_xxx

Or pass key directly (for automation):

BIRDSAFE_MCP_KEY=mcp_sk_xxx birdsafe-mcp-service

3) Client Configuration

Claude Desktop Example

Add this configuration to your Claude Desktop MCP config file:

{
  "mcpServers": {
    "birdsafe": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/birdsafe-mcp-service/src/server.mjs"],
      "env": {
        "BIRDSAFE_API_BASE": "https://api.birdsafe.nan0.in"
      }
    }
  }
}

Claude Code

Claude Code has built-in MCP support. After running init, it auto-discovers and connects.

cd /path/to/your/project
birdsafe-mcp-service --init

After initialization in your project directory, Claude Code can discover .birdsafe-mcp/config.json and connect automatically.

Other MCP Clients

OpenClou and other MCP-compatible clients use the same configuration pattern.

4) Verification & Troubleshooting

First verify your key is valid:

curl -X GET 'https://api.birdsafe.nan0.in/api/mcp/me' \
  -H 'Authorization: Bearer mcp_sk_xxx'

• If you get 401: reset the key in BirdSafe settings and run init again.
• If the client shows tools (birdsafe_me, birdsafe_query_tweets, birdsafe_recent_tweets), setup is complete.