Connecting

You need a MeshMesh workspace to connect — you sign in with the same account you use for the app, and your role decides which tools you get.

Endpoint

POST https://gateway.meshmesh.io/mcp

The server speaks Streamable HTTP (MCP's HTTP transport). It is stateless — every request is a single POST. There is no stdio or SSE endpoint, and GET/DELETE return 405.

Authentication

The server uses OAuth 2.0. Your MCP client obtains a token through the standard authorization flow and sends it as a bearer token:

Authorization: Bearer <token>

Clients discover the authorization server automatically — no manual setup beyond signing in:

GET https://gateway.meshmesh.io/.well-known/oauth-protected-resource
GET https://gateway.meshmesh.io/.well-known/oauth-authorization-server

A request with no token gets a 401 whose WWW-Authenticate header points at the discovery URL, which is the client's cue to start the OAuth flow. Your MeshMesh identity and workspace are taken from the token, so the tools you can see and call match your role (see Roles & access).

Most MCP clients handle OAuth for you: paste the URL, and the client opens a browser window to sign in. You do not create or paste an API key.

Connecting from popular clients

Any MCP client that supports remote (HTTP) servers with OAuth works. On first use each client opens a browser to sign in; after that the model can call MeshMesh tools. Pick your client below.

Add the server, then authenticate:

claude mcp add --transport http meshmesh https://gateway.meshmesh.io/mcp

In a Claude Code session, run /mcp and complete the browser sign-in. Verify with:

claude mcp list

Add --scope user (all your projects) or --scope project (shared via a checked-in .mcp.json) to change where the server is saved.

Add the server to ~/.codex/config.toml:

[mcp_servers.meshmesh]
url = "https://gateway.meshmesh.io/mcp"

Then sign in:

codex mcp login meshmesh

Support for remote (HTTP) MCP servers with OAuth is recent in Codex — update to the latest CLI (npm i -g @openai/codex@latest) and check the Codex docs for the current mcp command if codex mcp login isn't recognized. Use url (not command/args, which are for local servers).

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "meshmesh": {
      "url": "https://gateway.meshmesh.io/mcp"
    }
  }
}

Cursor detects that the server needs OAuth and prompts you to sign in — no token goes in the file.

Add the server to .vscode/mcp.json:

{
  "servers": {
    "meshmesh": {
      "type": "http",
      "url": "https://gateway.meshmesh.io/mcp"
    }
  }
}

Or run MCP: Add Server from the Command Palette and paste the URL.

VS Code uses the key servers and requires "type": "http" — different from Cursor's mcpServers.

Connect through the UI:

Settings → Connectors → Add custom connector
Name it meshmesh and enter the URL https://gateway.meshmesh.io/mcp
Click Add and complete the browser sign-in.

MeshMesh tools then appear in the message composer's connectors menu.

Custom connectors require a Claude plan that supports them. If you don't see Add custom connector, your plan may not include it.

Your first call

Once connected, confirm it works by asking your client to call get_user_details — it should return your email and workspace. Then kick off real work:

start_agent with a name and a prompt — this returns an agentId.
get_agent_status to watch progress and see when it's waiting on you.
get_plan then continue_agent to approve the plan or send a follow-up.

See the full tool reference for everything else.

Troubleshooting

Sign-in loops or "needs authentication": re-run the client's auth step (in Claude Code, /mcp). Tokens refresh automatically, but you can always clear and re-authenticate.
405 errors: the server only accepts POST at /mcp — make sure your client is configured for HTTP transport, not SSE.
A tool is missing: it's likely admin-only and hidden for your role. See Roles & access.