Skip to main content

AI Agent Integration

The Alien Intelligence platform exposes your document collections to AI assistants — Claude, GPT, custom agents — through the Model Context Protocol (MCP). AI agents can search, read, and analyze your documents using the same data that powers the platform's search features, without any custom integration code.

What Is MCP?​

MCP is an open protocol that lets AI assistants call structured tools provided by external servers. Instead of the AI guessing or hallucinating, it can call a tool like datacluster_vector_search_chunks to search your actual data and get real results.

The platform hosts MCP servers that wrap your data cluster's search and retrieval capabilities as tools that AI agents can invoke directly.

Available MCP Servers​

MCP ServerToolsData SourceDescription
mcp-datacluster7Your data clustersSearch and read your documents — the primary integration point
Custom MCP Servers

We can build customized MCP servers for your specific data sources, similar to what we have done for research intelligence and cultural heritage organizations. Contact us at support@alien.club to discuss your needs.

mcp-datacluster Tools​

This is the MCP server deployed on your data cluster. It provides tools for the complete document access workflow:

ToolWhat It Does
datacluster_list_datasetsList available datasets with metadata
datacluster_get_datasetGet full details of a specific dataset including schema
datacluster_keyword_searchFull-text keyword search with typo tolerance and filters
datacluster_vector_search_chunksSemantic search — find chunks by meaning similarity
datacluster_get_entry_contentRead the processed content of a document (paginated)
datacluster_get_entry_documentsList files attached to an entry
datacluster_get_entry_fileDownload a specific file (including extracted figures as viewable images)

An AI agent can use these tools to autonomously navigate your document collection: discover datasets, search for relevant documents, read their content, and examine their figures.

Connecting an AI Agent​

Authentication​

MCP servers use OAuth for authentication. When an AI agent connects to an MCP server, the following flow occurs:

The agent inherits the authenticated user's permissions — it can only access data that the user is authorized to see.

Enterprise Authentication Bypass​

For programmatic or server-to-server MCP access, you can bypass the interactive OAuth flow by injecting an API token directly in the request headers. This is useful for automated pipelines, backend integrations, and scenarios where interactive login is not possible.

The MCP server supports two token formats:

  • Platform API tokens (oat_* format) — Validated against the platform backend via the /users/me endpoint. The server extracts user identity, organization context, and token abilities from the backend response.
  • JWT tokens — Validated via OIDC introspection against the identity provider. Used when your application authenticates directly with the identity provider.

Configuration with API Token​

To connect an AI tool (such as Claude Desktop or Claude Code) using an API token, configure the MCP server with an Authorization header:

{
  "mcpServers": {
    "my-data-cluster": {
      "type": "http",
      "url": "https://YOUR_MCP_SERVER_URL/mcp",
      "headers": {
        "Authorization": "Bearer oat_YOUR_API_TOKEN"
      }
    }
  }
}

This configuration goes in:

  • Claude Desktop: claude_desktop_config.json (Settings > MCP Servers)
  • Claude Code: .mcp.json in your project root

The MCP server URL is available from the MCP section of the platform dashboard after deployment. See Deploy MCP for details on deploying an MCP server and finding the connection URL.

tip

When using API token authentication, the token's abilities determine what the agent can do. Ensure the token has at least CLUSTER_READ and DATASET_READ abilities for search operations.

Connecting Claude Desktop​

To connect Claude Desktop to your document collection:

  1. Deploy an MCP server on your data cluster if you have not already.
  2. Navigate to MCP in the left sidebar of the platform dashboard.
  3. Find your cluster and expand its MCP connection details.
  4. Copy the claude_desktop_config.json snippet shown in the connection card.
  5. In Claude Desktop, go to Settings > MCP Servers and paste the configuration.
  6. Claude will either use the embedded API token (if present) or prompt you to authenticate via OAuth.

Once connected, you can ask Claude to search and analyze your documents directly:

"Search my research papers for studies about CRISPR gene editing in agricultural applications and summarize the key findings."

Claude will use the MCP tools to search your data cluster, read the relevant documents, and provide a grounded answer based on your actual data.

Connecting Other AI Agents​

Any AI agent or application that supports the MCP protocol can connect to the platform's MCP servers. The connection requires:

  1. Server URL — Available from the MCP section of the platform dashboard after deploying an MCP server.
  2. Authentication — OAuth flow for interactive use, or API token header for programmatic access.

The MCP servers expose a standard /.well-known/oauth-authorization-server endpoint for OAuth discovery and a /health endpoint for connectivity verification.

Per-Tool Access Control​

Each MCP tool declares the permissions it requires. For example, datacluster_keyword_search requires both dataset:read and entry:read abilities. The platform enforces these checks on every tool invocation — an agent cannot access data that the authenticated user does not have permission to see.

Organization-level roles determine what an agent can do:

RoleCan Use
ViewerAll read-only tools (list, search, get content)
WriterRead-only tools + tools that modify data (if available)
OwnerAll tools

Example: Research Workflow​

Here is how an AI agent might use MCP tools to answer a research question:

1. datacluster_list_datasets
   → Discovers "biomedical-papers" dataset (5,000 entries)

2. datacluster_vector_search_chunks
   query: "CRISPR applications in crop disease resistance"
   → Returns 10 relevant chunks with similarity scores

3. datacluster_get_entry_content
   entry_id: 4521, page: 1
   → Reads the full processed content of the top result

4. datacluster_get_entry_documents
   entry_id: 4521
   → Lists files: original PDF, 3 extracted figures

5. datacluster_get_entry_file
   entry_id: 4521, file_key: "processed/figures/figure_2.png"
   → Returns the figure image for the AI to analyze

The agent performs all of these steps autonomously, following the data to build a comprehensive answer.

Managing MCP Servers​

The MCP section in the left sidebar shows all MCP servers available to your organization. From this page you can:

  • Deploy or undeploy MCP servers on your clusters.
  • View the connection URL and configuration snippet for each server.
  • Check server health status.
  • See which tools each server provides.

For step-by-step deployment instructions, see Deploy MCP.

Next Steps​