Guides
Home

Synaccess Cloud MCP with Claude Code

This guide explains how to connect Claude Code directly to Synaccess Cloud MCP. This is useful for developers, operators, and integrators who want to inspect Synaccess Cloud CMP data from Claude Code without building a Slack integration first.

When to Use This Option

Use this option when:

  • You want to test Synaccess Cloud MCP from a terminal.
  • A developer or operator needs direct MCP access.
  • You want to validate tool behavior before wiring Slack or another application.
  • You are troubleshooting Synaccess MCP authentication, scopes, or tool responses.

How It Works

Claude Code
  -> Synaccess Cloud MCP
  -> Synaccess Cloud CMP data
  -> Claude Code response

Claude Code connects to the remote Synaccess MCP endpoint using HTTP and sends your Synaccess Cloud Personal Access Token as a bearer token.

Prerequisites

Before starting, make sure you have:

  • Claude Code installed.

  • A Synaccess Cloud account with access to the devices you want to query.

  • MCP access enabled for your Synaccess enterprise.

  • A Synaccess Cloud Personal Access Token.

  • A deployed Synaccess Cloud MCP endpoint:

    https://<synaccess-mcp-host>/mcp

Your token can only access the devices and data that your Synaccess Cloud account can access.

Create a Personal Access Token

  1. Sign in to Synaccess Cloud.
  2. Open your user or account settings.
  3. Go to API Access.
  4. Create a new Personal Access Token.
  5. Copy the token when it is shown.

Store the token securely. Synaccess Cloud only shows the full token when it is created.

Recommended Setup: Environment Variable

Use an environment variable so the PAT is not written directly into prompts or project files.

export SYNACCESS_PAT="<your Synaccess Cloud Personal Access Token>"

Add the MCP server with JSON:

claude mcp add-json --scope user synaccess-cloud \
  '{"type":"http","url":"https://<synaccess-mcp-host>/mcp","headers":{"Authorization":"Bearer ${SYNACCESS_PAT}"}}'

The single quotes keep ${SYNACCESS_PAT} from being expanded by your shell when the config is written. Claude Code can expand it when it starts.

Before starting Claude Code in a new shell, export the token:

export SYNACCESS_PAT="<your Synaccess Cloud Personal Access Token>"
claude

Quick Local Setup

For a fast one-machine test, you can add the token directly:

claude mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer <your Synaccess Cloud Personal Access Token>" \
  synaccess-cloud \
  https://<synaccess-mcp-host>/mcp

This is convenient, but it stores the resolved token in your local Claude Code configuration. Prefer the environment-variable setup for regular use.

Project-Level Setup

Use a project-level .mcp.json only when everyone working in that project should have the Synaccess MCP server available. Keep each user's token in their own shell environment.

{
  "mcpServers": {
    "synaccess-cloud": {
      "type": "http",
      "url": "https://<synaccess-mcp-host>/mcp",
      "headers": {
        "Authorization": "Bearer ${SYNACCESS_PAT}"
      }
    }
  }
}

Do not commit real tokens to .mcp.json.

Verify the Connection

Start Claude Code:

claude

Use:

/mcp

Confirm that synaccess-cloud is connected.

Then try:

List my Synaccess devices and summarize their connection status.

or:

Get a fleet summary from Synaccess Cloud.

Security Checklist

  • Do not paste PATs into prompts.
  • Do not commit PATs to .mcp.json, shell history, or project files.
  • Prefer environment variable expansion for regular use.
  • Use a PAT that belongs to the operator who needs access.
  • Delete or rotate tokens that are no longer needed.
  • Remember that MCP access is still bounded by Synaccess Cloud user permissions and enterprise MCP access.

Troubleshooting

Claude Code says authentication failed

Check that:

  • SYNACCESS_PAT is exported in the same shell where Claude Code starts.

  • The MCP URL ends with /mcp.

  • The config uses type: "http".

  • The Authorization header is exactly:

    Bearer <token>

  • The token is active in Synaccess Cloud.

  • MCP access is enabled for your Synaccess enterprise.

Test the Synaccess token directly

Use:

curl -sS -i \
  "https://cloud.synaccess.com/v1/auth/me" \
  -H "Authorization: Bearer ${SYNACCESS_PAT}"

A working token should return 200.

Test the MCP endpoint directly

Use:

curl -sS -i \
  -X POST "https://<synaccess-mcp-host>/mcp" \
  -H "Authorization: Bearer ${SYNACCESS_PAT}" \
  -H "Content-Type: application/json" \
  --data '{}'

If authentication fails, the response should include an error description that helps identify whether the token, enterprise MCP access, or scopes are the issue.

Claude Code still uses an old token

Remove and re-add the server:

claude mcp remove synaccess-cloud

export SYNACCESS_PAT="<your new Synaccess Cloud Personal Access Token>"

claude mcp add-json --scope user synaccess-cloud \
  '{"type":"http","url":"https://<synaccess-mcp-host>/mcp","headers":{"Authorization":"Bearer ${SYNACCESS_PAT}"}}'

Then restart Claude Code and check /mcp again.

References