Skip to main content

Use Spectral MCP With Cursor

Connect Cursor to Spectral through the Model Context Protocol (MCP) to create structural models and edit model elements while working in your editor.

Spectral uses remote HTTP MCP at:

https://viewer.spectralco.co/mcp

Requirements​

  • Cursor installed and signed in.
  • A Spectral account that can sign in through https://viewer.spectralco.co.
  • Network access to https://viewer.spectralco.co/mcp and https://viewer.spectralco.co.
  • Permission to add either a project MCP config or a personal global MCP config.
  • OAuth scopes:
    • mcp:models:read
    • mcp:models:write

Cursor supports remote MCP servers over Streamable HTTP. Spectral's public MCP server should be configured with url, not a local command.

Choose A Config Location​

Cursor reads MCP server configuration from either:

.cursor/mcp.json
~/.cursor/mcp.json

Use .cursor/mcp.json for repo-specific setup that should travel with a project. Use ~/.cursor/mcp.json for personal setup that should be available in all Cursor workspaces on your machine.

The OAuth config below does not include a client secret.

Set Up Spectral With OAuth​

1. Create or open mcp.json​

For project-specific setup, create:

.cursor/mcp.json

For personal setup, create:

~/.cursor/mcp.json

2. Add the Spectral server​

Paste this OAuth configuration:

{
  "mcpServers": {
    "spectral": {
      "url": "https://viewer.spectralco.co/mcp",
      "auth": {
        "CLIENT_ID": "spectral-cursor",
        "scopes": ["mcp:models:read", "mcp:models:write"]
      }
    }
  }
}

Spectral's Cursor OAuth client must allow Cursor's fixed MCP redirect URI:

cursor://anysphere.cursor-mcp/oauth/callback

Cursor uses this redirect URI for MCP OAuth and identifies the server through OAuth state.

3. Reload Cursor and authenticate​

Reload the Cursor window or restart Cursor so the MCP config is read. Open Settings, go to Features, then Model Context Protocol, and confirm spectral appears. Complete the OAuth prompt when Cursor asks you to authenticate.

You can also ask Cursor to use Spectral in chat. Cursor will show Spectral tools under Available Tools when the server is connected.

4. Review tool approvals​

Cursor asks for approval before running MCP tools by default. Expand the tool call to review arguments, especially for write tools such as model creation or element insertion.

Test Model Creation​

Use a small test prompt:

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

Review the planned tool arguments before approving the call.

What Spectral Can Access​

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

  • mcp:models:read allows returning viewer payloads for created models.
  • mcp:models:write allows creating or changing model data.

The production MCP surface is Code Mode:

  • search
  • get_schema
  • execute

Use search and get_schema to discover Spectral model operations, then use execute to call operations such as spectral.create_model, spectral.create_nodes, spectral.create_member, and spectral.get_viewer_model.

Example Workflows​

Try prompts like:

  • "Create a new Spectral model named Cursor smoke test."
  • "Add a small frame-element example to the model, then show me the viewer link."
  • "Prepare a nodes-and-frames JSON payload from this file and ask before using Spectral to create the model."

Privacy And Data Handling​

When you connect Spectral through MCP, Cursor can receive the model data, metadata, UI resources, and tool results needed to complete your prompt. That data may be included in the chat context handled by Cursor and the model provider selected in your Cursor workspace.

Spectral receives MCP requests from Cursor, 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 Cursor to create sensitive model data unless that data is allowed to be processed by your Cursor workspace, selected model provider, and Spectral account.

Disconnect Or Remove Spectral​

To disconnect Spectral:

  1. Remove the spectral entry from .cursor/mcp.json or ~/.cursor/mcp.json.
  2. Reload the Cursor window or restart Cursor.
  3. Open Settings, go to Features, then Model Context Protocol, and confirm the server no longer appears.

To temporarily stop using Spectral without changing the config, disable the server from Cursor's Model Context Protocol settings.

Troubleshooting​

Spectral does not appear in Cursor​

Check that the file is named exactly .cursor/mcp.json or ~/.cursor/mcp.json, that the JSON is valid, and that the config contains a top-level mcpServers object. Reload the Cursor window after changes.

OAuth does not complete​

Confirm the Spectral OAuth client allows:

cursor://anysphere.cursor-mcp/oauth/callback

Then restart Cursor and try the authentication flow again.

A tool call returns 401 or 403​

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

A tool call fails or times out​

Open the Output panel in Cursor, select MCP Logs, and check for connection, authentication, or server errors. Confirm the URL is exactly:

https://viewer.spectralco.co/mcp

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.

Cursor wants to run a write tool​

Cursor asks for MCP tool approval by default. Review the tool name and arguments before approving model creation or element insertion.

Help And Next Steps​

  • Read the Spectral MCP overview at /docs/mcp/overview.
  • Review Spectral MCP authentication at /docs/mcp/authentication.
  • See Cursor's MCP reference at https://cursor.com/docs/mcp.md.
  • When asking for help, include your Cursor version, whether the config is project or global, and the relevant MCP Logs entry.