flipside-mcp-extension/README.md

Flipside Intelligence via MCP

What it is

An AI agent that acts as your personal blockchain data scientist, accessible directly through Claude Desktop via Model Context Protocol (MCP).

How it works

Natural language interface to Flipside's curated blockchain datasets and embedded analytical workflows. Simply ask questions in plain English and get sophisticated blockchain analytics instantly.

Key capabilities

• Complex Analysis Made Simple: Execute cohort analysis, user journey mapping, and trend detection through conversational queries
• Comprehensive Data Access: Query data across 30+ blockchain networks with billions of indexed transactions
• Proprietary Insights: Access Flipside's specialized scoring algorithms and predictive metrics
• Domain Expertise: Leverage years of blockchain growth intelligence embedded in AI workflows

The Vision

Democratize blockchain data science expertise. For the first time, any stakeholder—from ecosystem CEOs to community managers—can conduct sophisticated blockchain analysis without years of technical training.

Integration

Available through Claude Desktop's MCP integration, bringing enterprise-grade blockchain analytics directly into your workflow without switching tools or platforms.

---

Flipside Intelligence transforms specialized data science expertise into accessible AI-powered tools, making blockchain growth insights available to everyone.

Technical Features

• Zero Dependencies: Self-contained Go binary with no runtime requirements
• Cross-Platform: Supports macOS, Linux, and Windows (x64 and ARM64)
• Secure Connection: Environment-based configuration with encrypted API key authentication
• Real-time Analytics: Direct access to live blockchain data streams
• Optimized Performance: Lightweight proxy design for seamless Claude Desktop integration

Configuration

The proxy is configured via environment variables:

Variable	Required	Description	Example
MCP_REMOTE_URL	Yes	Flipside Intelligence MCP endpoint	https://mcp.flipsidecrypto.xyz/beta/sse
FLIPSIDE_API_KEY	Yes	Your Flipside API key for authenticated access	your-api-key-here
MCP_DEBUG	No	Enable debug logging	true or false

Installation

As a Claude Desktop Extension (Recommended)

1. Download the appropriate .dxt file for your platform from releases
2. Import the DXT file into Claude Desktop
3. Configure your Flipside API key and MCP endpoint in the extension settings
4. Start analyzing blockchain data with natural language queries in Claude Desktop

Manual Installation

1. Download the binary for your platform:

   • macOS (Intel): remote-mcp-proxy-darwin-amd64
   • macOS (Apple Silicon): remote-mcp-proxy-darwin-arm64
   • Linux (x64): remote-mcp-proxy-linux-amd64
   • Linux (ARM64): remote-mcp-proxy-linux-arm64
   • Windows (x64): remote-mcp-proxy-windows-amd64.exe
   • Windows (ARM64): remote-mcp-proxy-windows-arm64.exe

2. Make executable (Unix-like systems):

   chmod +x remote-mcp-proxy-*
   

3. Configure environment variables:

   export MCP_REMOTE_URL="https://mcp.flipsidecrypto.xyz/beta/sse"
   export FLIPSIDE_API_KEY="your-api-key-here"
   export MCP_DEBUG="false"  # Optional
   

4. Run the proxy:

   ./remote-mcp-proxy-darwin-amd64
   

Usage Examples

Once connected through Claude Desktop, you can ask natural language questions like:

• "Show me the top 10 DeFi protocols by TVL on Ethereum this week"
• "Analyze user retention patterns for Uniswap v3 over the last 6 months"
• "What's the correlation between gas prices and DEX trading volume?"
• "Create a cohort analysis of new wallet addresses on Polygon"

The extension handles all the technical complexity, translating your questions into sophisticated blockchain queries and returning actionable insights.

Getting Your API Key

To access Flipside Intelligence:

1. Visit flipsidecrypto.xyz
2. Create an account or sign in
3. Navigate to your API settings to generate your key
4. Use this key in the extension configuration

Development

Building from Source

# Install dependencies
make deps

# Build and package both Go and Node.js desktop extensions
make dxt-all

# Build just the Go desktop extension
make dxt

# Build just the Node.js desktop extension
make dxt-node

# Create tar.gz packages (alternative format)
make dxt-tar

Note: The DXT packages are properly formatted for Claude Desktop. The Go implementation provides a cross-platform proxy binary, while the Node.js implementation uses npx mcp-remote for a simpler setup.

Creating Releases

The project uses tag-based releases that trigger automatic builds and publishing via GitHub Actions:

# Create a patch release (e.g., 1.2.3 -> 1.2.4)
make release-patch

# Create a minor release (e.g., 1.2.3 -> 1.3.0)  
make release-minor

# Create a major release (e.g., 1.2.3 -> 2.0.0)
make release-major

Release Process:

1. Choose release type based on your changes:

   • patch: Bug fixes, small improvements
   • minor: New features, backward-compatible changes
   • major: Breaking changes

2. Run the release command - it will:

   • Show current version and calculated new version
   • Ask for confirmation before proceeding
   • Create and push the version tag to GitHub

3. GitHub Actions automatically:

   • Builds binaries for all platforms
   • Creates a GitHub release
   • Uploads DXT and tar.gz packages
   • Updates the manifest.json with the new version

Manual Release (if needed):

# Create and push a version tag manually
git tag v1.3.0
git push origin v1.3.0

The release will be available at: https://github.com/flipside-org/flipside-mcp-extension/releases

Project Structure

/
├── main.go           # Go proxy implementation
├── manifest.json     # Go extension manifest
├── node/            # Node.js implementation
│   ├── manifest.json # Node.js extension manifest
│   └── icon.png     # Extension icon
├── Makefile         # Build automation
├── README.md        # This file
├── go.mod           # Go module definition
└── dist/            # Build artifacts (created by make)

Testing

The project includes comprehensive unit tests for the proxy server functionality:

# Run unit tests
go test -v

# Run tests with coverage
go test -v -race -coverprofile=coverage.out

# View coverage report
go tool cover -html=coverage.out

# Run tests via Makefile (includes functional testing)
make test

Test Coverage:

• Proxy creation and configuration
• Client authentication (Bearer tokens + query parameters)
• URL conversion (SSE → MCP endpoints)
• Error handling and network failures
• API key security (masking functionality)
• Integration testing with mock MCP server

CI/CD Pipeline

All pull requests and pushes to main automatically run:

Test Workflow:

• Unit tests with race detection and coverage reporting
• Cross-platform build verification (Linux, macOS, Windows)
• Code quality checks with golangci-lint
• Security scanning with gosec and govulncheck
• Makefile integration testing

Quality Gates:

• All tests must pass before merge
• Code coverage tracking via Codecov
• Security vulnerabilities blocking deployment
• Linting errors preventing merge

To ensure your PR passes CI:

# Run the same checks locally
go test -v -race -coverprofile=coverage.out
go build -v .
make test

Dependencies

• mark3labs/mcp-go - MCP protocol implementation for Go
• @anthropic-ai/dxt - For packaging desktop extensions
• mcp-remote - For Node.js implementation

Security Considerations

• The proxy forwards all requests to the configured remote URL
• Ensure your remote MCP server implements proper authentication and authorization
• Use HTTPS URLs for production deployments
• Consider network timeouts and rate limiting on the server side

Troubleshooting

Enable Debug Logging

Set MCP_DEBUG=true to see detailed request/response logs:

MCP_DEBUG=true MCP_REMOTE_URL=https://mcp.flipsidecrypto.xyz/beta/sse FLIPSIDE_API_KEY=your-key ./flipside-mcp-extension

Common Issues

1. Authentication failed: Verify your Flipside API key is correct and active
2. Connection refused: Check your internet connection and firewall settings
3. Timeout errors: Large queries may take time; try breaking them into smaller requests
4. Rate limiting: Ensure you're within your API plan limits

License

MIT License - see the project root for details.

Support

For issues and questions:

• GitHub Issues: flipside-org/flipside-mcp-extension
• Documentation: docs.flipsidecrypto.xyz
• Email: support@flipside.xyz