Authenticated MCP server

The MCP server speaks the same project → file → job → output loop as the app. It is authenticated. Unauthenticated calls get 401 and a WWW-Authenticate header that points at OAuth metadata.

Endpoint

https://api.quickmdsim.com/mcp

The app host also proxies the same handler at https://app.quickmdsim.com/api/mcp. Prefer the api.quickmdsim.com origin for OAuth (authorize + token live there).

Grok (OAuth 2.1 + PKCE)

Grok’s custom connector asks for OAuth credentials. Use the first-party public client — no secret. Token auth method is PKCE only.

1. You need a QuickMDSim account (same as the app). Email must be verified before jobs run.
2. In Grok: New Connector → Custom → URL https://api.quickmdsim.com/mcp
3. When it asks for OAuth:

• Client ID: quickmdsim-mcp
• Client secret: leave blank
• Authorization endpoint: https://api.quickmdsim.com/oauth/authorize
• Token endpoint: https://api.quickmdsim.com/oauth/token
• Scopes: mcp
• Token auth method: none (PKCE only)

Grok then opens the QuickMDSim sign-in page. Sign in, click Allow. The redirect URI Grok sends (grokbot://mcp/oauth/callback or an https grok.com callback) is already allowed on this client.

Hermes / Claude / Cursor (personal access token)

1. Open Account in the app.
2. Under API tokens, name it and click Create token.
3. Copy the qmd_… secret. It is shown once. Revoke it any time from the same page.

Header: Authorization: Bearer qmd_YOUR_TOKEN

Hermes

hermes mcp add quickmdsim --url https://api.quickmdsim.com/mcp

Then put the token in ~/.hermes/config.yaml:

mcp_servers:
  quickmdsim:
    url: https://api.quickmdsim.com/mcp
    headers:
      Authorization: "Bearer qmd_YOUR_TOKEN"
    timeout: 180

Restart Hermes (or /reload-mcp). Tools show up as mcp_quickmdsim_*. Smoke test: hermes mcp test quickmdsim.

Claude Desktop / Claude Code

In Claude Desktop settings → MCP, or in claude_desktop_config.json:

{
  "mcpServers": {
    "quickmdsim": {
      "url": "https://api.quickmdsim.com/mcp",
      "headers": {
        "Authorization": "Bearer qmd_YOUR_TOKEN"
      }
    }
  }
}

Claude Code: claude mcp add --transport http quickmdsim https://api.quickmdsim.com/mcp and add the same Authorization header in the generated config. Clients that speak MCP OAuth can also register dynamically at https://api.quickmdsim.com/oauth/register (RFC 7591) instead of using a PAT.

Cursor

In .cursor/mcp.json or Cursor Settings → MCP:

{
  "mcpServers": {
    "quickmdsim": {
      "url": "https://api.quickmdsim.com/mcp",
      "headers": {
        "Authorization": "Bearer qmd_YOUR_TOKEN"
      }
    }
  }
}

Usage loop

Ask the agent to do the work. A typical first job:

1. whoami — confirm the account, credits, and that jobs can run
2. create_project — name it
3. write_file — put a real input.lammps (overwrite the stub). Prefer attach_potential for library pots
4. submit_job — optional vcpus of 1, 2, or 4 (Free is 1 only)
5. get_job — poll until status_label is done or failed
6. list_outputs then read_output for stdout.txt / the log, or get_trajectory for a 3D dump

Binary outputs (movies, snapshots) stay in the app — MCP returns text logs and dump excerpts, not mp4/png bytes.

Tools

• whoami — account, plan, credits, allowed cores
• list_projects / create_project / get_project
• list_files / read_file / write_file
• list_potentials / get_potential / attach_potential — search the hosted library, then attach a read-only pot (you pick the filename). See potential library
• list_jobs / submit_job / get_job
• list_outputs / read_output / get_trajectory

A token or OAuth grant sees only that account. Revoking a PAT takes effect on the next call. Treat qmd_… like a password — do not commit it.

If something fails

• 401 — missing/revoked token, expired OAuth access token, or the Bearer header did not arrive
• Verify your email — same as the app; jobs stay blocked until the link is clicked
• Insufficient credits — check whoami, then Account → Subscriptions
• No LAMMPS input script — data.lammps is a topology file; write input.lammps that calls read_data
• Upgrade to run on 2 or 4 cores — Free is 1 vCPU
• Grok invalid_redirect_uri — the first-party client already allows grokbot://mcp/oauth/callback. If Grok shows a different URI, tell us and we will add it.