Uxxu MCP for LLMs

Uxxu MCP

Connect your AI client to read project context, create C4 models and diagrams, and push the result straight into your Uxxu workspace. Instead of generating throwaway pictures, your LLM creates real diagrams with layout, relationships, and technologies already wired in.

Configure your clientGet a Uxxu API Key

1. Connect

Add the hosted MCP URL and your organisation API key to a compatible HTTP MCP client. No local server is needed.

2. Teach

Add a skill or instruction layer so the model understands how to map a specification into system context, container, and component diagrams.

3. Generate

Ask for a diagram in plain English. Uxxu handles layout, connectors, technology matching, and stores the final result in your project.

Quick Summary

The fast version

This is the shortest explanation of the workflow.

  • Connect to the hosted MCP with your organisation API key.
  • Teach your model basic C4 mapping rules with a skill or instruction pack.
  • Give it a written specification and let it create or update the C4 model in Uxxu.

Example Prompt

Use the uxxu MCP. In my Uxxu project "Architecture Demo", create a C4 system context diagram for a food delivery platform with consumers, couriers, restaurant managers, a dispatching platform, real-time status updates, Stripe Connect, Twilio, and Google Maps.

What Uxxu adds

  • project and diagram context tools for the LLM
  • automatic ELK layout and connector selection
  • technology matching against the Uxxu catalog
  • viewer links to the created diagram

Connect your AI client

One hosted endpoint, scoped to your organisation. No Uxxu server or npm package to install.

1. Prepare your organisation and API key

  1. Sign in to Uxxu and select the organisation you want the AI client to access.
  2. Open your account settings and find API Keys. Create a separate, expiring key for this client. Start with VIEW; add CREATE, UPDATE, or DELETE only when needed.
  3. Copy the full key when it is shown. Keep it in your secret manager, not a prompt, screenshot, URL, or committed configuration file.
  4. From a project page, copy the organisation ID: the first segment after app.uxxu.io in the address, before /projects. Replace YOUR_ORGANIZATION_ID in the configuration below.
https://app.uxxu.io/api/mcp/YOUR_ORGANIZATION_ID

Use the URL without a trailing slash. The header must be Authorization: ApiKey followed by your full key. Your browser login cookie is not used.

2. Configure your client

These examples use the clients' documented HTTP settings. Uxxu supports the 2025 Streamable HTTP handshake and MCP 2026-07-28 on the same endpoint. Use a current client and verify read-only access before enabling writes.

.mcp.json

Merge this entry into .mcp.json at your project root. Make UXXU_API_KEY available to Claude Code before starting it, then approve the project server when prompted.

{
  "mcpServers": {
    "uxxu": {
      "type": "http",
      "url": "https://app.uxxu.io/api/mcp/YOUR_ORGANIZATION_ID",
      "headers": {
        "Authorization": "ApiKey ${UXXU_API_KEY}"
      }
    }
  }
}

Run /mcp in Claude Code to inspect the connection and available tools.

Official Claude Code MCP documentation
Set credentials for a terminal-launched client

In bash or zsh, run this without putting your key in shell history, then launch the client from the same terminal. For a desktop client, provide the variables through its launch environment. VS Code's masked prompt does not need these variables.

# macOS / Linux: enter the key at the hidden prompt
printf 'Uxxu API key: '
read -r -s UXXU_API_KEY
printf '\n'
export UXXU_API_KEY

# Codex reads the complete Authorization header value
export UXXU_AUTH_HEADER="ApiKey $UXXU_API_KEY"

3. Verify read-only access

Confirm that the client discovers the Uxxu tools, then send this first prompt. An empty project list is valid for a new organisation.

Use the uxxu MCP to list the projects in my connected organisation. Read uxxu://guides/c4-modeling. Summarise what you can access without creating, changing, or deleting anything.

After this succeeds, grant only the write permissions you need and try a small diagram in a test project. Requests have a 25-second server deadline; configure a client timeout of at least 30 seconds. Check for partial changes before retrying a timed-out write.

Claude web, Desktop, and other clients

The Claude instructions above are for Claude Code. The Claude web and Desktop remote-connector flow is not supported by this API-key-only setup. Uxxu does not provide an OAuth login flow yet. Never put your API key in a connector URL.

Other clients need Streamable HTTP and a custom Authorization header. A URL-only or OAuth-only connection is not sufficient. See Claude's remote-connector documentation.

Connection troubleshooting

401: authentication
Check the full key, expiry, revocation, environment variable, and the ApiKey prefix. Do not send a Bearer token or browser cookie.
403: organisation or permissions
Check that the URL uses the key's organisation and that the key has VIEW access. Writes require the corresponding permissions.
Missing Authentication Token
This API Gateway response can mean the route or HTTP method is missing. Check the exact URL and contact info@uxxu.io; changing your key may not fix it.
Unsupported protocol or failed handshake
Select HTTP / Streamable HTTP, not a legacy SSE-only transport or a local command. Update the client. The endpoint supports 2025 HTTP initialization and MCP 2026-07-28; contact info@uxxu.io if negotiation still fails.
429 or timeout
The service is busy or the request is too large to finish in time. Wait, inspect the project, and split large changes into smaller calls. Do not blindly retry writes.

Why this workflow matters

Most LLM-assisted architecture work still starts with long prose prompts. That helps at first, but it breaks down when the model needs a stable view of boundaries, actors, and dependencies. The Uxxu MCP fixes that by giving the model tools that work against a real architecture workspace.

That creates a better feedback loop. The model can inspect project context, turn a written specification into a real C4 diagram, and return a live viewer link. The result is not a throwaway image in a chat. It becomes part of the shared architecture model your team keeps using.

Modeling Guide

The MCP provides the tools; the modeling guide explains how to inspect project context and map specifications into connected C4 diagrams.

Read the MCP resource:
uxxu://guides/c4-modeling

For a stronger setup, install the `uxxu-mcp-diagrams` skill so the model learns your preferred C4 mapping rules and prompt patterns.

Control Access

Give each AI client only the permissions it needs. A read-only key can inspect the model; editing requires the corresponding write permissions.

VIEW: inspect projects and diagrams
CREATE / UPDATE / DELETE: enable only as needed

Revoke the API key to stop future requests. Revocation cannot undo changes already accepted by the backend.

Teach the model, not just the tool

The MCP gives the model capabilities. A skill or instruction pack gives it judgment. That is how you get reliable results for system context, container, and component diagrams instead of generic box-and-arrow output.

What the skill should teach

  • how to distinguish actors, systems, containers, and stores
  • how to keep links at the right C4 level
  • how to name elements consistently
  • when to reuse an existing diagram vs create a new one

What Uxxu handles after that

  • diagram creation in your project
  • element placement and parent-child layout
  • relationship connectors
  • technology matching and viewer links

What teams can do with this

Once the MCP and skill are in place, the workflow becomes much more interesting than a simple “generate me a diagram” demo. Teams can ask the model to create a first-pass architecture from a specification, compare an existing diagram against a proposed change, suggest missing relationships, turn project context into an LLM prompt for deeper code reasoning, or create several diagram levels that all belong to the same logical model in Uxxu.

That is why we see this as more than an integration page. It is a different way of working with architecture: diagrams as a language between humans and models, with Uxxu as the place where those diagrams remain structured, connected, and useful after the chat ends.