Adding MCP Servers to AIVA¶

AIVA allows you to connect external Model Context Protocol (MCP) servers, extending the AI assistant with your own data sources, APIs, and analysis pipelines. Once configured, MCP tools appear alongside AIVA's built-in tools and can be invoked automatically during conversations.

Video Walkthrough¶

Common Use Cases¶

• Internal databases: Connect AIVA to institutional variant databases, LIMS, or EHR systems.
• Custom analysis pipelines: Expose bioinformatics pipelines or custom scoring algorithms as tools.
• Proprietary knowledge bases: Make internal curated knowledge (e.g., institutional classification databases) available to AIVA.
• Third-party APIs: Integrate external services not included in AIVA's default tool set (e.g., OpenTargets, OpenCRAVAT).

Configuring MCP Servers¶

Open the MCP Server Configuration dialog from the chat interface. The dialog has two tabs: JSON Configuration and Tool Management.

JSON Configuration¶

The JSON Configuration tab is where you add MCP server connections.

Quick Add presets: Click a preset button (e.g., OpenCRAVAT, OpenTargets) to instantly populate the JSON configuration for popular genomic MCP servers.

Custom servers: Enter MCP server configuration directly in the JSON editor. The format follows the standard MCP configuration schema:

{
  "mcpServers": {
    "opentargets": {
      "transport": "http",
      "url": "https://mcp.platform.opentargets.org/mcp"
    }
  }
}

After entering the configuration:

1. Click Test Connection to verify that AIVA can reach the server.
2. A success banner confirms the connection: "Connection tests complete! Click 'Select Tools' below to configure which tools to enable."
3. Click Select Tools to switch to the Tool Management tab and choose which tools to activate.

Tool Management¶

The Tool Management tab lets you select which tools from your MCP servers the AI agent can access.

• Tool limit: You can enable up to 10 MCP tools at a time across all configured servers.
• Per-server listing: Tools are grouped by server. Each server shows the number of available tools.
• Select All / Deselect All: Quickly enable or disable all tools from a specific server.
• Individual toggle: Enable or disable specific tools by clicking their checkboxes.

After selecting your tools, click Save Selection to apply the changes.

Using MCP Tools in Chat¶

Once configured, MCP tools work the same way as built-in tools:

• AIVA automatically selects MCP tools when your question matches the tool's description.
• You can see which MCP tool was invoked in the tool call indicator during the response.
• Results from MCP tools are displayed inline in the conversation.

You can also explicitly request an MCP tool by referencing it in your prompt:

"Use the OpenTargets tool to search for drug targets for EGFR."

Managing MCP Servers¶

Editing configuration¶

Update server URLs or add new servers from the JSON Configuration tab in the MCP Server Configuration dialog.

Removing a server¶

Delete a server's entry from the JSON configuration and click Save Selection. This removes its tools from AIVA but does not affect the external server.

Clearing all servers¶

Click Clear All in the MCP Server Configuration dialog to remove all configured servers at once.

Security Considerations¶

Troubleshooting¶