Home › Guides › AI assistants (MCP)

Use ArchLens from AI assistants (MCP)

ArchLens has a remote Model Context Protocol (MCP) server. Connect your AI assistant once and it can list your workspaces, read diagrams, and draw new ones into a draft that you review and merge.

The server

URL	`https://app.archlens.space/api/mcp`
Transport	streamable HTTP, stateless (POST only, JSON replies)
Sign-in	OAuth 2.1 with dynamic client registration and PKCE, or a personal bearer token
Acts as	the person who connected, with their role in each workspace (a viewer cannot write)

You need an ArchLens account: sign up with Google or GitHub.

Connect your assistant

Claude (claude.ai and Claude Desktop)

In Settings › Connectors, add a custom connector and paste https://app.archlens.space/api/mcp. Claude opens ArchLens; sign in and approve the connection. Custom connectors may depend on your Claude plan; see Claude's help center.

Claude Code

claude mcp add --transport http archlens https://app.archlens.space/api/mcp

Then run /mcp in Claude Code and sign in. With a personal token instead: add --header "Authorization: Bearer alk_...".

ChatGPT

Where your ChatGPT plan offers custom connectors (developer mode), add a connector with the URL https://app.archlens.space/api/mcp and OAuth authentication, then approve it in ArchLens. Menu names change between versions; see OpenAI's help center for the current steps.

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "archlens": { "url": "https://app.archlens.space/api/mcp" }
  }
}

VS Code

Run MCP: Add Server, choose HTTP and paste the URL, or add it to your MCP configuration:

{
  "servers": {
    "archlens": { "type": "http", "url": "https://app.archlens.space/api/mcp" }
  }
}

Any other client that supports remote MCP servers over streamable HTTP works the same way.

Sign-in: OAuth or a token

OAuth (recommended): clients that support it only need the URL. They discover ArchLens's authorization server, register themselves, and send you to ArchLens to approve. Access tokens last an hour and are renewed by the client.
Personal token: in ArchLens open Settings ⚙ › Profile › AI access tokens, name a token and create it. It is shown once; send it as Authorization: Bearer alk_.... You can hold up to 10.
Revoke a token or a connected app from the same section at any time. A token acts as you, so keep it secret.

Tools

Tool	Does
`list_workspaces`	your workspaces, with your role
`create_workspace`	a new, empty workspace (within your plan's limit)
`list_diagrams`	the diagrams of a workspace
`get_diagram`	a diagram as Mermaid C4 text, one block per level
`list_elements`	every object: id, name, type, parent, icon, and the diagrams it is on
`list_icons` / `set_icons`	technology logos, and setting them on objects
`merge_duplicates`	folds objects drawn twice into one (dry run first; saves a version before changing the live workspace)
`create_draft` / `discard_draft`	open an isolated copy of the workspace to edit, or drop it
`import_structurizr`	a new diagram from Structurizr DSL (or an ArchLens JSON file), reusing objects the workspace already has; returns its link
`delete_diagram`	deletes a diagram (owners only)
`clear_model`	empties the workspace's model: every object, line and flow (owners only; saves a version first)
`create_flow`	Unlimited plan: turns a scenario you describe into a flow over the diagram's connections
`explain_diagram`	Unlimited plan: every level's objects and connections and the flows, as text for the assistant to explain

A review-first workflow

The assistant never needs to touch your live diagrams. The server tells it to work like this:

list_workspaces to find the workspace.
create_draft to open a draft.
import_structurizr into that draft with a model written from your request.
It gives you the link. You open the draft in ArchLens, look at the difference, and merge it or discard it.

Things to ask:

"Read this repository and draw its C4 container diagram in my ArchLens workspace Platform, as a draft."
"Get the Checkout diagram and tell me which services talk to the payments provider."
"Set technology icons on the objects of the Shop diagram."

Start free with Google or GitHubConnect your assistant in two minutes.