MCP Connector FAQ

Common questions about connecting AI agents to the Alien Intelligence platform via MCP servers.

The platform exposes two types of MCP server, each with a different data model and tool set:

MCP Server Type	Tools Prefix	Data Model	Authentication
Data cluster (your documents)	datacluster_*	Datasets, entries, files, chunks	OAuth or API token (oat_*)
OpenAIRE (public research graph)	openaire_*	Publications, datasets, projects, authors, organizations	OAuth
bioRxiv / medRxiv (public preprints)	datacluster_*	Same as data cluster — datasets, entries, chunks	OAuth

Keep this distinction in mind when troubleshooting — the authentication model and error behavior differ between connector types.

Authentication

Q: My AI agent gets an "unauthorized" error on my data cluster MCP server.

A: Data cluster MCP servers support both OAuth and API token authentication. Check:

• If using an API token: verify it has not expired, belongs to the correct organization, and has at least CLUSTER_READ and DATASET_READ abilities. Generate a new token from Organization > API Users in the dashboard.
• If using OAuth: disconnect and reconnect the MCP server in your AI client to trigger a fresh OAuth flow.

See AI Agent Integration — Enterprise Authentication Bypass for API token configuration details.

Q: My AI agent gets an "unauthorized" error on the OpenAIRE or bioRxiv/medRxiv connector.

A: These public connectors use OAuth only — API tokens are not supported. The OAuth flow is initiated automatically when the AI agent first calls a tool. If authentication fails:

• Ensure you have an Alien Intelligence account.
• On claude.ai, OAuth triggers on the first tool call, not when the connector is added. Start a conversation and invoke a tool to trigger the login prompt.
• In Claude Code with the marketplace plugin, the MCP servers are pre-configured — if auth fails, try /reload-plugins and start a new conversation.

Q: The OAuth login page does not appear when I connect Claude Desktop.

A: If you configured Claude Desktop with an API token in the Authorization header, the OAuth flow is bypassed entirely. This is expected behavior and only applies to data cluster MCP servers. If you want interactive OAuth login instead, remove the headers section from your configuration and provide only the server URL.

Q: My AI agent's OAuth token expired and it stopped working.

A: OAuth access tokens are short-lived by design. Most AI clients (Claude Desktop, claude.ai, ChatGPT) handle token refresh automatically. If your agent stops working mid-session:

• On claude.ai or Claude Desktop: disconnect and reconnect the connector.
• In Claude Code: restart the session or run /reload-plugins.

Timeouts and Performance

Q: The AI agent's tool calls are timing out or returning slow results.

A: The cause depends on which connector the agent is using:

• Data cluster (datacluster_* tools): The agent may be running broad searches against a large dataset. The agent should use filters (date range, dataset name) and specific search terms when possible. If the issue persists, check that your data cluster is in an Active state in the platform dashboard.
• OpenAIRE (openaire_* tools): Some OpenAIRE tools produce very large responses — in particular get_project_outputs, analyze_coauthorship_network, and get_author_profile with high limits. The openscience plugin skill guides the agent to delegate these calls to subagents to avoid context overflow. If you are using the OpenAIRE connector without the plugin, consider prompting the agent to use smaller page sizes and minimal detail levels.
• bioRxiv / medRxiv: Same behavior as data cluster tools. Broad semantic searches across the full preprint corpus may be slower than keyword searches.

Q: The agent receives a "504 Gateway Timeout" error.

A: This indicates the upstream MCP server did not respond in time. Wait a few seconds and ask the agent to retry. If the issue persists:

• For data cluster MCP servers: check that your cluster is Active and the MCP server shows Running in the dashboard. See Deploy MCP troubleshooting.
• For OpenAIRE / bioRxiv / medRxiv: check status.alien.club for any ongoing service issues.

Rate Limits

Q: Am I subject to rate limits?

A: Alien Intelligence does not currently impose rate limits on MCP server requests. Third-party connectors (e.g. the OpenAIRE API upstream) may have their own rate limits — if the agent encounters rate limit errors from those services, prompt it to space out requests or reduce concurrent tool calls.

Data and Privacy

Q: Are my search queries stored?

A: No. MCP servers process queries in real time and do not store query content or results. See our Privacy Policy for full details on data handling.

Q: Can other organizations see my documents?

A: No. Each organization's data clusters are fully isolated — documents, search indices, and access tokens are scoped to the owning organization. The OpenAIRE and bioRxiv/medRxiv connectors serve public research metadata and are not organization-scoped. See Security Model for details.

MCP Server Connectivity

Q: How do I check if an MCP server is healthy?

A: For data cluster MCP servers:

1. In the platform dashboard, navigate to MCP and check the health status indicator for your cluster.
2. Send a GET request to https://your-cluster.mcp.alien.club/health — a 200 OK response confirms the server is running.

For public connectors (OpenAIRE, bioRxiv, medRxiv), check status.alien.club.

Q: My data cluster MCP server shows "Not Deployed" but I deployed it earlier.

A: An MCP server may be undeployed if your data cluster was scaled down, restarted, or updated. Navigate to the MCP section in the dashboard and redeploy the server. See Deploy MCP for instructions.

Q: The agent discovers tools but they return errors.

A: Common causes:

• Data cluster: The cluster has no datasets or no processed entries yet. Upload documents and wait for pipeline processing to complete.
• OpenAIRE: Some queries return 0 results due to sparse coverage in certain areas (e.g. dataset-to-publication links, person search). This is an upstream data limitation, not an error. The openscience plugin skill includes workarounds for known sparse areas.
• Permissions: Verify your organization role is Viewer or higher for read operations.