connect-partmode-to-an-agent

name	connect-partmode-to-an-agent
category	code
description	Configure and verify PartMode's hosted MCP server for a person's agent without exposing credentials or granting more CAD authority than needed. Use when they say "connect PartMode to Codex," "set up PartMode MCP," "add PartMode to my agent," or ask why the PartMode MCP URL does not behave like a normal web page.

connect-partmode-to-an-agent

Connect an MCP-capable agent to PartMode and leave behind a verified, revocable setup. Use the public reference at https://partmode.com/help#mcp-reference and treat live MCP discovery as the authority for the running release.

Boundaries

• Have the person create and revoke their own agent key at https://partmode.com/account. Never ask them to paste the key into chat, a URL, source code, a skill, or a tracked config file.
• Use https://partmode.com/mcp as a Streamable HTTP MCP endpoint. A normal browser visit is documentation traffic; MCP clients send authenticated JSON-RPC requests.
• Treat authentication and project authority separately. A key identifies the agent, but a browser project still needs visible approval.
• Request a headless grant only when unattended server CAD is actually needed. Existing keys cannot be silently upgraded.

Procedure

1. Open https://partmode.com/account. On the current production deployment, Google sign-in is not configured; create or sign in to a PartMode account with an account name and passphrase. Read the public MCP reference with the person and confirm their client supports Streamable HTTP MCP and secret environment variables.

2. In the signed-in dashboard, create a labeled key with the least power needed: read-only or edit, with headless server access disabled unless the planned workflow deliberately requires server execution and durable server-side project storage. PartMode shows the raw key once; if it is lost, revoke it and create another.

3. Put that one-time key in OS or client secret storage exposed to the agent as an environment variable such as PARTMODE_AGENT_KEY. Use a non-echoing input path rather than typing the value into a shell command. Check that shell history, project files, logs, and git status do not expose its value.

4. Configure the client with endpoint https://partmode.com/mcp and bearer authentication from that environment variable. For Codex, use:

   codex mcp add partmode --url https://partmode.com/mcp --bearer-token-env-var PARTMODE_AGENT_KEY
   

5. Restart the client, initialize the MCP connection, and call resources/list and tools/list. Read partmode://help/mcp-reference and partmode://help/agent-workflow when resources are available.

6. Choose one session path. For a visible browser project, call partmode_list_studios, request the smallest bounded connection with an explicit sessionSeconds and commit budget, and have the person confirm the visible project identity before approving it in the intended PartMode tab. For a granted headless key, open the named durable project explicitly.

7. Call partmode_session_status and confirm the returned mode, permissions, expiry, and remaining commit budget match the request. Abort and disconnect if the authority is broader or the duration is wrong.

8. Call cad_capabilities, then use cad_inspect or cad_query to compare the opened document with an expected name, revision, entity, or document fingerprint supplied by the person. Abort and disconnect on a mismatch. Record the verified session path, scope, expiry, budget, and current revision without recording the key.

9. End the test session with partmode_disconnect. Revoke any throwaway key the person created only for setup verification.

Done

• The agent lists live PartMode resources and tools through the hosted MCP URL
• A bounded session opens through visible approval or an explicit headless grant
• Session status proves the approved mode, permissions, expiry, and commit budget
• An exact document inspection matches the project evidence the person expected
• cad_capabilities returns the live capability manifest and current revision
• No credential appears in chat, source, tracked files, logs, or shell history
• The test session is disconnected and any temporary key is revoked