Using AIVA MCP with Other Agents¶

AIVA exposes a Model Context Protocol (MCP) server that allows MCP-compatible AI agents to access AIVA's genomic analysis tools directly. This means you can use AIVA's variant annotation, literature search, knowledge graph, and other tools from within your preferred AI assistant.

MCP Endpoint¶

https://api.aivaportal.com/mcp/sse

The MCP server uses Server-Sent Events (SSE) transport for real-time communication. All requests require authentication with an AIVA API key. See API Reference for instructions on creating a key.

Available Tools¶

Once connected, the following AIVA tools become available in your MCP client:

Tool	Description
Genomic Data Query	Query your uploaded variant data using SQL
Web Search	Search the web for genomic and biomedical information
Variant Annotation	Annotate variants with ClinVar, gnomAD, SIFT, etc.
Biomedical Literature	Search biomedical literature databases
Code Interpreter	Execute Python code for data analysis and visualization
Knowledge Graph	Query the gene-protein-drug interaction network
Clinical Trials	Search clinical trials databases
Phenotype-Gene Prioritization	Phenotype-to-gene prioritization

Claude Desktop¶

Add the AIVA MCP server to your Claude Desktop configuration to use AIVA's tools directly in Claude conversations.

Video walkthrough¶

Configuration¶

Add the AIVA MCP server to the mcpServers section of your Claude Desktop configuration file:

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.aivaportal.com/mcp/sse",
        "--header",
        "Authorization: Bearer <AIVA_API_KEY>"
      ]
    }
  }
}

Replace <AIVA_API_KEY> with your actual API key. Restart Claude Desktop after updating the configuration.

OpenAI Codex¶

Connect AIVA's tools to OpenAI Codex for AI-assisted genomic analysis within your coding workflow.

Video walkthrough¶

Other MCP-Compatible Clients¶

The AIVA MCP server works with any client that supports the MCP specification with SSE transport. Below are configuration patterns for popular tools.

Claude Code¶

Add AIVA as an MCP server in your Claude Code configuration by typing /mcp and selecting "Add MCP Server".

Cursor¶

In Cursor, navigate to Settings > MCP and add a new server with the AIVA endpoint URL and your API key.

Windsurf¶

In Windsurf, add the AIVA MCP server through the MCP configuration panel using the same endpoint URL and authentication header.

Troubleshooting¶

Issue	Resolution
Connection fails	Verify your API key is valid. See API Reference for details.
Invalid JSON	Ensure the configuration JSON is valid (no trailing commas, correct quoting).
Tools not loading	Restart your AI agent after making configuration changes.
Authentication errors	API keys are case-sensitive. Copy the key exactly as shown at creation time. If expired or revoked, create a new one from Settings > API Keys in AIVA.