Skip to main content

Use Spectral MCP with Claude Code

Connect Claude Code to Spectral through the Model Context Protocol (MCP) to create structural models and add model elements from your terminal.

Spectral uses remote HTTP MCP at:

https://mcp.spectralco.co/mcp

Requirements​

  • Claude Code installed, up to date, and signed in on your machine.
  • A Spectral account that can sign in through https://auth.spectralco.co.
  • Network access to https://mcp.spectralco.co/mcp and https://auth.spectralco.co.
  • OAuth scopes:
    • mcp:models:read
    • mcp:models:write

Spectral's public MCP endpoint is a remote HTTP server. Do not configure it as a local stdio server, and do not use SSE unless Spectral support asks you to test a specific fallback.

Set Up Spectral With OAuth​

1. Add the Spectral MCP server​

Run this from a terminal:

claude mcp add --transport http spectral https://mcp.spectralco.co/mcp

2. Start a fresh Claude Code session​

If Claude Code was already running, start a new session so the new MCP server is loaded:

claude

3. Authenticate Spectral​

Inside Claude Code, open the MCP server list:

/mcp

Select spectral, follow the browser sign-in flow, and authorize the requested Spectral scopes. When OAuth finishes, Claude Code can use Spectral tools in the current session.

4. Confirm the server is connected​

You can review the configured server from your terminal:

claude mcp list
claude mcp get spectral

You can also return to /mcp inside Claude Code to check the connection state and available tools.

Advanced: Pin Scopes Or OAuth Discovery​

Most users should use the command above. If OAuth discovery fails behind a proxy, or if your workspace needs to pin the requested scopes, configure authServerMetadataUrl and oauth.scopes in the server JSON:

{
  "mcpServers": {
    "spectral": {
      "type": "http",
      "url": "https://mcp.spectralco.co/mcp",
      "oauth": {
        "scopes": "mcp:models:read mcp:models:write",
        "authServerMetadataUrl": "https://auth.spectralco.co/.well-known/oauth-authorization-server"
      }
    }
  }
}

Use the advanced fallback only when standard OAuth discovery does not find Spectral's authorization metadata.

Test Model Creation​

Use a small test prompt:

Use Spectral to create an empty model named Claude Code MCP Smoke Test.

Review the planned tool arguments before approving the call.

What Spectral Can Access​

After authorization, Claude Code can ask Spectral to use the permissions you granted:

  • mcp:models:read allows returning viewer payloads for created models.
  • mcp:models:write allows creating models and adding model elements.

The current public MCP surface for these docs is:

  • spectral.create_model
  • spectral.add_model_elements
  • spectral.get_viewer_model

Review write actions before approving them. A write-capable Claude Code session can create or change Spectral model data when you ask it to do so.

Example Workflows​

Try prompts like:

  • "Create a new Spectral model named Claude Code smoke test."
  • "Add a small frame-element example to the new model, then show me the viewer link."
  • "Build a JSON payload for four columns and two beams, show the payload, then create the model in Spectral."

Privacy And Data Handling​

When you connect Spectral through MCP, Claude Code can receive the model data, metadata, and tool results needed to complete your prompt. That data may be included in the conversation context handled by Claude Code.

Spectral receives MCP requests from Claude Code, including your authenticated Spectral identity, granted scopes, requested tool names, model identifiers, and tool inputs. Spectral may keep operational logs for security, debugging, and audit purposes.

Do not ask Claude Code to create sensitive model data unless that data is allowed to be processed by your Claude Code workspace and Spectral account.

Disconnect Or Remove Spectral​

To remove the server from Claude Code:

claude mcp remove spectral

To clear OAuth credentials without removing the server, open /mcp, select spectral, and use the clear-authentication action.

Troubleshooting​

claude mcp add is not recognized​

Update Claude Code and confirm the claude command is on your PATH.

The OAuth browser window does not open​

Run /mcp again. If Claude Code prints an authorization URL, copy it into your browser manually. If the browser redirect fails after sign-in, paste the full callback URL from the browser address bar back into the prompt shown by Claude Code.

Spectral is listed but tools are not available​

Start a fresh Claude Code session after adding the server. Existing sessions may not load newly added MCP servers. Then run /mcp and confirm spectral is connected, not pending approval or failed.

OAuth discovery fails​

Use the advanced JSON configuration and set:

https://auth.spectralco.co/.well-known/oauth-authorization-server

as oauth.authServerMetadataUrl.

A tool call returns 403 insufficient_scope​

Reconnect OAuth and approve both mcp:models:read and mcp:models:write.

GET /mcp returns 405 Method Not Allowed​

That response is expected for Spectral's Streamable HTTP MCP endpoint. MCP clients connect by using the protocol over HTTP requests to /mcp.

Help And Next Steps​

  • Read the Spectral MCP overview at /docs/mcp/overview.
  • Review Spectral MCP authentication at /docs/mcp/authentication.
  • See Claude Code's MCP reference at https://code.claude.com/docs/en/mcp.
  • When asking for help, include your Claude Code version, the exact server name spectral, and the error shown in /mcp or claude mcp get spectral.