Relevance MCP Server

A Smithery-compatible MCP (Model Context Protocol) server that exposes Relevance AI tools to MCP clients.

Overview

This server allows you to use your Relevance AI tools through any MCP-compatible client. Simply configure it with your Relevance AI credentials and the tool IDs you want to expose, and the server will dynamically register them as MCP tools.

Features

• Dynamic Tool Registration: Automatically fetches and registers Relevance AI tools based on configuration
• Type-Safe Configuration: Uses Zod schemas for robust configuration validation
• Async Tool Execution: Handles Relevance AI's async job execution pattern
• Error Handling: Comprehensive error handling for API failures and timeouts
• Unit Tests: Includes Jest-based unit tests for configuration and server logic

Prerequisites

• Node.js >= 18
• A Relevance AI account
• Relevance AI API credentials:
  • API Key
  • Region (e.g., "us", "au")
  • Project UUID
  • Tool IDs you want to expose

Getting Started

Installation

npm install

Configuration

The server requires the following configuration parameters:

• apiKey: Your Relevance AI API key (found in Account > Integrations > Relevance API keys)
• region: Your Relevance AI region (e.g., "us", "au")
• project: Your Relevance AI project UUID
• toolIds: Array of Relevance AI tool IDs to expose as MCP tools

Development

Run the server in development mode with Smithery:

npm run dev

This will start the server and make it available through the Smithery Playground.

Testing

Run the unit tests:

npm test

Building

Build the server for production:

npm run build

Deployment

Deploy to Smithery

1. Create a GitHub repository and push your code:

git remote add origin https://github.com/YOUR_USERNAME/relevance_mcp.git
git push -u origin main

2. Go to Smithery and click "Deploy"
3. Connect your GitHub repository
4. Configure your Relevance AI credentials in the deployment settings

How It Works

1. Configuration: The server reads your Relevance AI credentials and tool IDs from the configuration
2. Tool Discovery: On startup, it fetches metadata for each configured tool from the Relevance AI API
3. Schema Mapping: It converts Relevance AI parameter schemas to MCP-compatible Zod schemas
4. Tool Registration: Each Relevance AI tool is registered as an MCP tool
5. Execution: When a tool is called:
   • The server triggers the Relevance AI tool with the provided parameters
   • It polls the job status until completion (max 60 seconds)
   • The output is returned in MCP format

API Reference

Relevance AI Client

The RelevanceClient class handles all interactions with the Relevance AI API:

• listTools(): Lists all available tools in your project
• retrieveTool(toolId): Retrieves metadata for a specific tool
• executeTool(toolId, params): Triggers async execution of a tool
• getJobStatus(toolId, jobId): Checks the status of a job
• waitForJobCompletion(toolId, jobId, timeout): Waits for a job to complete

Architecture

src/
├── index.ts              # Main MCP server implementation
├── relevance-client.ts   # Relevance AI API client
test/
├── config.test.ts        # Configuration schema tests
├── server.test.ts        # Server logic tests

Troubleshooting

Tool not found

Make sure the tool ID exists in your Relevance AI project and is accessible with your API key.

Authentication errors

Verify that your API key, region, and project UUID are correct. You can find these in your Relevance AI account under Account > Integrations.

Timeout errors

The default timeout is 60 seconds. If your tool takes longer to execute, you may need to modify the timeout in relevance-client.ts.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Resources

• Relevance AI Documentation
• Relevance AI SDK
• Smithery Documentation
• MCP TypeScript SDK