+ Documentation

Use your own AI assistant

Graphite4D can work with an AI assistant you already use, such as Claude or Codex, through the Model Context Protocol (MCP). Your assistant reads your project, checks Graphite's modeling guide, and submits proposals. Nothing changes in your model until you open the proposal in Graphite, look at the geometry, and choose Approve change.

Because the assistant runs in your own AI app, its usage counts against your own AI subscription, not your Graphite plan.

How it works

Chat inside Graphite

In the Design assistant panel, ask for a change and it applies directly to your open project or design alternative. There is no comparison or approval step. Images and files can accompany your message as context.

The composer keeps your message on the top row and its controls underneath:

• Plus opens attachments, view capture, skill selection and execution location.
• AI permissions offers Ask only, Selected elements or Whole project. Ask only cannot change the design. Selected elements limits edits to the selected construction; connected geometry may still update. Whole project allows edits throughout the open project or alternative.
• Model and effort lets you choose a model and how much effort it should use. Higher effort can take longer and use more tokens. Your effort preference is remembered separately for each model on this browser.
• Dictation adds spoken words to your draft in supported browsers. Stop the microphone and review the words before sending; dictation never sends for you.
• Send submits your message. New messages scroll into view automatically.

The text box grows as you type. To run a background task, choose Plus → Background task, then send; the task dialog sets its spending limit. Background tasks use a separate design alternative, and their result is reviewed before merging. Selected-element permission also limits background work. Ask only runs in chat.

To undo one AI response, select the small Revert AI changes icon beside it, then confirm Revert changes. Rewind also works after reopening the project. Independent edits you made afterward are kept. If later work changes the same parts, Graphite explains the conflict instead of overwriting that work.

If an answer was saved but its changes could not be applied, Retry changes tries the saved edits again without generating another answer.

Connected external assistants

1. Open Client access for your project. When browser sign-in is enabled, connect through your assistant and approve its requested permissions in Graphite. Otherwise, create a project credential; Graphite shows it once.
2. Add the matching URL and authentication settings to your AI app, or configure the local bridge for geometry tools.
3. You ask your assistant for a change. It inspects the project and submits a proposal.
4. You open the proposal inbox in Graphite, compare the original and proposed designs, adjust them if you like, and approve or discard.

The assistant cannot approve or discard proposals, change the saved model directly, create or revoke credentials, or open any other project. Those actions stay in the signed-in Graphite app.

What your assistant can do

Hosted MCP provides get_modeling_guide, inspect_project, propose_change, get_proposal_status, inspect_proposal, refine_proposal and save_project_copy. The evaluation, geometry, capture and drawing tools below require the local bridge.

Pictures from capture_view are quick geometry previews with plain colors. Textures, image lighting and perforation patterns appear only in the Graphite viewport.

Before you start

• A Graphite4D project that is saved to the cloud.
• The owner or administrator role in the workspace. Only owners and administrators can create client access.
• An active editing seat for the person who creates the client access. Proposals are refused without one.
• For hosted MCP: an AI app that accepts a Streamable HTTP URL with a bearer credential or the enabled browser sign-in flow, such as Codex.
• For the local bridge: an AI app that runs local MCP servers, Node.js (opens in a new tab) 24 or newer, and a supplied copy of the bridge with dependencies installed.

Create client access

1. Open the project in Graphite.
2. Open the project menu at the right end of the top bar and choose External design clients.
3. Select Client access.
4. Enter a Client name you will recognize later, such as Claude Desktop on my laptop, and select Create client access.
5. Select Copy credential. The credential is shown only this once and expires in 30 days.
6. Under Connect your assistant, choose Codex, HTTP client, or Local bridge and follow its settings.

Keep the credential private. Do not paste it into a chat, a shared document or a screenshot. If it is exposed, select Revoke next to its name and create a new one.

Each credential covers one project. To work on another project, create client access in that project and add a second server entry with its own project ID and credential.

Connect Codex with hosted MCP

When browser sign-in is enabled:

1. Open Client access → Connect your assistant → Codex and copy the configuration into ~/.codex/config.toml.
2. Choose Authenticate in Codex's MCP settings, or run the displayed codex mcp login command.
3. Sign in to Graphite. Check the client, workspace, project and requested permissions, then select Allow connection.
4. Ask Codex to inspect the connected project. Additional proposal or save-copy permissions require a new consent when requested.

The configuration contains no credential. Codex identifies itself through its published client metadata and stores the resulting project credential in its configured OAuth credential store. You can revoke access from Graphite at any time. See Codex's MCP configuration documentation (opens in a new tab).

For a manual project credential:

1. In Client access → Connect your assistant → Codex, select Copy configuration.
2. Add that entry to ~/.codex/config.toml. It contains the project URL and the name of a project-specific token environment variable.
3. Set that variable to the project credential in the environment that starts Codex, then restart Codex. Keep the token in your local secret settings; the copied configuration contains no secret.
4. Ask Codex: “Inspect the connected Graphite project and summarize its construction without changing it.”

If the panel shows browser sign-in instructions, expand Use a project credential instead and choose Copy manual configuration. The manual entry uses Codex's bearer_token_env_var setting.

For another HTTP client, copy the Hosted MCP URL from the HTTP client tab, select Streamable HTTP and bearer-token authentication, and enter the credential in the client’s secure settings. A URL alone cannot grant access.

Developers with the Graphite repository can run a read-only network check from web:

npm run check:mcp

Supply GRAPHITE4D_MCP_URL and GRAPHITE4D_PROJECT_TOKEN through the process environment. The check lists tools and inspects the project summary without creating a proposal or printing the credential or model contents. It accepts HTTPS, or HTTP on localhost for development, and refuses redirects.

Connect Claude Desktop

1. In Claude Desktop, open Settings → Developer → Edit Config. This opens claude_desktop_config.json.
2. Add a graphite entry under mcpServers, as shown below, using the full path to the bridge's server.mjs file and your own project ID and credential.
3. Save the file, then quit and reopen Claude Desktop.

{
  "mcpServers": {
    "graphite": {
      "command": "node",
      "args": ["/path/to/graphite-bridge/tools/mcp/server.mjs"],
      "env": {
        "GRAPHITE4D_URL": "https://app.graphite4d.com",
        "GRAPHITE4D_PROJECT_ID": "your-project-id",
        "GRAPHITE4D_PROJECT_TOKEN": "your-credential"
      }
    }
  }
}

The settings still use the product's earlier name, Graphite4D. Keep the variable names exactly as shown.

Connect Claude Code

Run this in a terminal, with the full path to the bridge and your own values:

claude mcp add graphite --scope user \
  --env GRAPHITE4D_URL=https://app.graphite4d.com \
  --env GRAPHITE4D_PROJECT_ID=your-project-id \
  --env GRAPHITE4D_PROJECT_TOKEN=your-credential \
  -- node /path/to/graphite-bridge/tools/mcp/server.mjs

Claude Code stores the credential in its own settings file. The command may also be kept in your shell history, so clear that entry afterward if other people use your account.

Connect other MCP apps

Any app that can launch a local MCP server over standard input and output can use the bridge. Give it these settings:

Apps that cannot launch local processes need a hosted connection with compatible authentication. When enabled, browser sign-in supports public OAuth clients with published HTTPS client metadata (CIMD), as well as pre-registered clients. It does not support dynamic registration or signed client assertions.

Ask for a change

The example below includes geometry evaluation through the local bridge. With hosted MCP, ask for a proposal and inspect its geometry during review in Graphite.

Start a new conversation and describe what you want. It helps to ask the assistant to read the guide and inspect the project first, for example:

Use the Graphite tools. Read the modeling guide, inspect my project, then propose
widening the main mass to 40 feet and adding a 10 by 20 foot porch, 8 feet tall,
on the east side. Evaluate the proposal and check that the two parts touch but
do not overlap.

You can describe sizes in feet and inches. Graphite stores lengths in meters internally, and the modeling guide tells the assistant how to convert them. Graphite shows the result in feet and inches.

The assistant may need a few attempts. When an edit is not valid, Graphite explains why, and the assistant can correct the edit and submit again. Proposals are checked against the latest saved model, so if you save a change while the assistant is working, it inspects the project again before proposing.

Review a proposal

1. In Graphite, open the project menu and choose External design clients. The Proposal inbox lists each proposal with its summary.
2. Select Refresh if a new proposal has not appeared yet. Graphite does not yet show a notification when one arrives.
3. Select Review proposal. Graphite builds the proposed geometry and highlights it in the viewport.
4. Switch between Original and Proposed to compare them. You can select parts and change their controls in the inspector.
5. Select Approve change to apply it, or Discard to close it without changing the model.

An approved proposal is saved as one design edit, so Undo reverses it. The assistant can see the outcome with get_proposal_status. You can review one proposal at a time; finish or discard the current one before opening another.

Work on a proposal together

If you adjust a proposal and want the assistant to continue from your version, select Sync with connected AI. This shares your edits and brings in any refinements the assistant has made since the last sync. Your own choices take precedence. The assistant sees your changes only after you sync, so ask it to inspect the proposal again.

Keep a design

Ask the assistant to save a copy when it has produced something worth returning to. It uses save_project_copy with a name and a short description. The copy appears under Project menu → Saved projects, and the original project is not changed or approved.

When a credential expires or is revoked

Manual credentials last 30 days. After one expires or is revoked, every project tool returns:

HTTP 401: Project credential expired, revoked, or does not cover this project.

To reconnect, create new client access for the project, replace the credential in your AI app’s secure settings or its configured token environment variable, and restart the app. There is no automatic renewal.

Browser sign-in connections renew short-lived tokens automatically, up to 90 days from consent. After that limit, revocation or refresh expiry, sign in and review the project again. Revocation stops tool access immediately.

Client access also stops working when the person who created it loses the owner or administrator role, leaves the workspace, or has their account suspended. Rejoining does not restore old credentials. Create new ones. A project can have up to 20 active credentials.

Troubleshooting

Privacy

When you connect an assistant, it can read the complete construction of the connected project, including names, notes and parameters. That information is sent to your AI provider under the terms of your AI subscription. The assistant cannot read your other projects, your workspace members or your billing details. You can see and revoke every client under External design clients → Client access.