devion-mcp-server/SETUP.md

MCP server for Devion blockchain infrastructure - AI-native blockchain data access for developers and AI agents

# 🛠️ Devion MCP Server Setup Guide

Complete setup instructions for integrating blockchain data into Claude Desktop via MCP.

## 📋 **Prerequisites**

- Node.js 18+ installed
- Claude Desktop application
- Devion API key (Growth tier or higher)

## 🚀 **Step-by-Step Setup** 

### **1. Get Your Devion API Key**

1. Visit [devion.dev](https://devion.dev) and create an account
2. Upgrade to **Growth tier** (required for MCP access)
3. Generate an API key from your dashboard
4. Copy the API key (starts with `dv_`)

### **2. Install the MCP Server**

```bash
# Install globally via NPM
npm install -g devion-mcp-server

# Verify installation
devion-mcp-server --version
```

### **3. Configure Claude Desktop**

**macOS:**
```bash
# Open configuration file
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
# Open configuration file  
code %APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
# Open configuration file
code ~/.config/Claude/claude_desktop_config.json
```

### **4. Add Devion MCP Configuration**

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "devion": {
      "command": "devion-mcp-server",
      "env": {
        "DEVION_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}
```

**⚠️ Important:** Replace `your-actual-api-key-here` with your real Devion API key.

### **5. Restart Claude Desktop**

1. Completely quit Claude Desktop
2. Restart the application
3. Look for the 🔧 tools icon in a new conversation

## ✅ **Verify Setup**

Test that everything works by asking Claude:

```
"What's the current block number on Ethereum mainnet?"
```

Claude should respond with real blockchain data using the Devion MCP server.

## 🔧 **Troubleshooting**

### **Common Issues**

#### **"No MCP tools available"**
- Check that Claude Desktop was completely restarted
- Verify the JSON configuration is valid (no trailing commas)
- Ensure the API key is correctly set

#### **"DEVION_API_KEY is required"**
- Double-check your API key in the configuration
- Make sure you're using the actual key, not a placeholder
- Verify you have Growth tier access

#### **"Permission denied" or command not found**
```bash
# Make sure the MCP server is installed globally
npm list -g devion-mcp-server

# If not found, reinstall
npm install -g devion-mcp-server
```

#### **"API key invalid" errors**
- Verify your API key is active in the Devion dashboard
- Check that you have Growth tier subscription
- Try regenerating the API key

### **Debug Mode**

Enable debug logging to troubleshoot issues:

```json
{
  "mcpServers": {
    "devion": {
      "command": "devion-mcp-server",
      "env": {
        "DEVION_API_KEY": "your-api-key",
        "DEBUG": "true"
      }
    }
  }
}
```

### **Manual Testing**

Test the MCP server manually:

```bash
# Set your API key
export DEVION_API_KEY="your-api-key"

# Test the server
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | devion-mcp-server
```

## 📁 **Configuration File Locations**

| OS | Path |
|----|------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |

## 🔄 **Updates**

Keep your MCP server updated:

```bash
# Check current version
npm list -g devion-mcp-server

# Update to latest version
npm update -g devion-mcp-server

# After updating, restart Claude Desktop
```

## 🛡️ **Security Best Practices**

1. **Never commit your API key** to version control
2. **Use environment variables** in production setups
3. **Rotate your API keys** regularly
4. **Monitor your usage** in the Devion dashboard

## 🆘 **Getting Help**

If you encounter issues:

1. **Check this troubleshooting guide** first
2. **Search our documentation** at [devion.dev/docs](https://devion.dev/docs)
3. **Join our Discord** for community support
4. **Email support** at support@devion.dev

## 🎯 **Next Steps**

Once setup is complete:

1. **Try the example prompts** in the README
2. **Explore all available tools** and their capabilities  
3. **Join our Discord** to share your AI × blockchain creations
4. **Follow our blog** for advanced tutorials and use cases

**Happy building! 🚀**