MCP for AI agents

Type: How-to · Audience: MCP users and developers building AI agents

The Molecule Studio MCP drives the scientific API: ligand resolution, pocket detection, docking, molecular rendering, simulation, uploads, versioned projects, provenance, jobs, and billing. Query tools/list for the exact catalogue installed on the server.

The cloud package uses the official MCP TypeScript SDK v2 packages. It supports the stateless 2026-07-28 protocol and the stateful dated protocol era through 2025-11-25, including compatible 2025-06-18 clients.

Hosted cloud MCP — API key

A hosted deployment exposes the packaged Streamable HTTP server and authenticates requests with Molecule Studio API keys:

{
  "mcpServers": {
    "molecule-studio": {
      "url": "https://moleculestud.io/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_your_key_here"
      }
    }
  }
}

The Molecule Studio application routes /mcp to the hosted endpoint at https://moleculestud.io/mcp. Authenticate with an API-key bearer token; the route does not implement an OAuth authorization flow.

Local stdio — API key

Use stdio when the client launches a local process:

{
  "mcpServers": {
    "molecule-studio": {
      "command": "npx",
      "args": ["-y", "@moleculestudio/mcp"],
      "env": {
        "MOLECULE_STUDIO_API_KEY": "ms_live_your_key_here",
        "MOLECULE_STUDIO_API_URL": "https://moleculestud.io"
      }
    }
  }
}

MOLECULE_STUDIO_API_KEY is required for stdio. MOLECULE_STUDIO_API_URL defaults to https://moleculestud.io. Official MCP conformance in CI targets the running cloud HTTP server because the official server runner is URL-based; it does not establish stdio conformance.

Self-hosted Streamable HTTP — API key

npm install -g @moleculestudio/mcp
MOLECULE_STUDIO_API_URL=https://moleculestud.io \
MCP_ALLOWED_HOSTS=mcp.example.com \
molecule-studio-mcp-http

{
  "mcpServers": {
    "molecule-studio-self-hosted": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_your_key_here"
      }
    }
  }
}

Each POST /mcp must send Authorization: Bearer ms_live_… or ms_test_…. The standalone process binds loopback unless MCP_HOST is explicitly set. Put TLS and any public exposure behind a hardened reverse proxy.

Implemented server environment variables

Variable	Default	Purpose
MOLECULE_STUDIO_API_URL	https://moleculestud.io	API origin used by cloud tools
MOLECULE_STUDIO_API_KEY	none	Required by stdio; HTTP authenticates each request
PORT	3333	HTTP listen port
MCP_HOST	127.0.0.1	HTTP bind address
MCP_ALLOWED_HOSTS	loopback hosts	Additional comma-separated Host values
MCP_ALLOWED_ORIGINS	loopback origins	Additional comma-separated browser origins
MCP_MAX_BODY_BYTES	1048576	Maximum JSON request body
MCP_RESOURCE_URL	none	Optional protected-resource metadata URL
MCP_AUTHORIZATION_SERVERS	none	Optional authorization-server metadata
MCP_SCOPES_SUPPORTED	none	Optional scopes included in protected-resource metadata
MCP_AUDIT_LOG	true	Set to false to disable structured request audit events

The three metadata variables only publish discovery metadata. They do not provide authorization or token validation and do not change the standalone CLI from API-key authentication. An embedding service must supply its own authenticate integration for another bearer-token scheme.

Upload behavior

Cloud upload tools mint intents and presigned URLs; the MCP server never reads a local path or transfers file bytes. The MCP host must read bounded chunks, PUT them directly to object storage, call complete_upload, and pass the returned key to a submit tool. A generic client without filesystem and HTTP transfer capabilities cannot upload files.

Troubleshooting

• Unknown tool: reconnect or restart the client so it refreshes tools/list.
• Hosted/self-hosted 401: verify the API key and required scopes against https://your-deployment.example/api/v1/credits/balance.
• Modern request rejected: send protocol version 2026-07-28 in request metadata and MCP-Protocol-Version, plus matching Mcp-Method and, where required, Mcp-Name headers.
• Stateful request rejected: negotiate a dated protocol revision through 2025-11-25; compatible older clients may negotiate 2025-06-18.