vecura-mcp-server

Working on this repo with an AI agent? Read AGENTS.md first — it covers the architecture decisions and the upstream contract gotchas.

MCP server exposing Vecura's bio/drug-discovery models to LLM agents.

Thin by design: it authenticates the caller and forwards to existing services. The schema and submission logic live in vecura-app, so a job submitted through MCP and one submitted through the tool page take the same code path.

Tools

Tool	Status	Backing call
FindTools	✅	GET {BACKEND}/api/v1/life-science-models/
GetToolDetail	✅	GET {APP}/api/agent-tools/model-schema/{id}
SubmitTool	✅	POST {APP}/api/agent-tools/tool-runs
GetJobStatus	✅	GET {APP}/api/workflow/{orgId}/tool-runs/{id}

Auth

Clients send Authorization: Bearer <JWT> — the same token the frontend gets from GET {AUTH_SERVICE_URL}/v1/token. The token is verified against the auth service's JWKS (via Hono's built-in jwk middleware, with the key set cached here) and forwarded downstream, so every job is created as the real user with their org membership, role and credits. There is no service account.

orgId comes from the token's session.activeOrganizationId, which pins one organization per token: switching orgs requires a new token.

Unlike vecura-workflow (which leaves JWT_ISSUER/JWT_AUDIENCE unset), this server always verifies iss and aud — it is the internet-facing entry point.

Configuration

Env	Default	Purpose
AUTH_SERVICE_URL	http://localhost:8080	Better Auth service
AUTH_JWKS_URL	${AUTH_SERVICE_URL}/v1/jwks	JWKS endpoint
AUTH_JWT_ISSUER	origin of AUTH_SERVICE_URL	Expected iss
AUTH_JWT_AUDIENCE	origin of AUTH_SERVICE_URL	Expected aud
VECURA_BACKEND_URL	http://localhost:8011	Model catalog
VECURA_APP_URL	http://localhost:3000	Next.js app: schema + submit routes, and the /api/workflow/* proxy
PORT	3100	Listen port (3000 is vecura-app's dev server)

The iss/aud defaults match Better Auth, which signs both as the auth service's base-URL origin.

Running

pnpm install
cp .env.example .env   # optional — defaults in src/config.ts work for a local stack
pnpm dev            # tsx watch
pnpm build && pnpm start

Smoke test (expects 401 without a token):

curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:3100/mcp \
  -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Note on the MCP server lifecycle

src/index.ts builds a new McpServer per request. A module-level instance — as shown in the hono-mcp docs — fails from the second request onward with Already connected to a transport, because Protocol.connect refuses to rebind (@modelcontextprotocol/sdk shared/protocol.js:215-218). Guarding that with isConnected() instead would make every caller share one transport, which is not a safe boundary when each request carries a different user's identity.