Introduction

The AlphaSOC MCP server connects AI agents (Claude Code, Claude Desktop, Cursor, opencode, and other Model Context Protocol clients) to your AlphaSOC workspace. Instead of switching to the console to answer "what fired last night" or "is this domain malicious", you ask in conversation and the agent queries AlphaSOC directly.

Setup

AlphaSOC hosts the MCP server, so there is nothing to install and no local process to run. Clients connect to a single remote endpoint over the MCP Streamable HTTP transport:

https://api.alphasoc.net/mcp

Authentication is the same browser sign-in the console uses, over OAuth: the client opens the AlphaSOC login page, you sign in with your AlphaSOC account, and there are no API keys to create or manage. Access tokens are short-lived; most clients refresh them silently, but a client without refresh-token support will ask you to sign in again from time to time.

All you need is an AlphaSOC account with membership of at least one workspace, and an MCP client that supports remote servers over Streamable HTTP with OAuth.

Claude Code

claude mcp add --transport http alphasoc https://api.alphasoc.net/mcp \
  --client-id mcp-client \
  --callback-port 9876

Then start claude, run /mcp, select alphasoc, and authenticate. A browser window opens for the AlphaSOC login; once it completes, /mcp lists the server and its tools. claude mcp list reports the same from the shell.

Use --callback-port 9877 if port 9876 is already in use on your machine, and add --scope user to register the server for every project rather than the current directory only.

tip

On a machine with no browser (an SSH session, or Linux with no display server) Claude Code prints the authorization URL instead of opening one, then asks you to paste the redirect URL back. That paste step needs an interactive terminal, so connect with ssh -t.

Claude.ai and Claude Desktop

Add https://api.alphasoc.net/mcp as a custom connector in settings, and enter mcp-client as the OAuth client ID under the connector's advanced settings. There is no port to configure; approve the connector and complete the AlphaSOC login in the browser.

Cursor

Add a remote entry under mcpServers, either in .cursor/mcp.json at the project root or in ~/.cursor/mcp.json to make it available in every project:

{
  "mcpServers": {
    "AlphaSOC": {
      "url": "https://api.alphasoc.net/mcp",
      "auth": {
        "CLIENT_ID": "mcp-client"
      }
    }
  }
}

The auth block is required; keep it exactly as shown. There is no client secret to add and no callback port to choose.

Then open Cursor's MCP settings, find AlphaSOC, and complete the browser login. Cursor shows the server as needing authentication until that finishes, after which its tools are listed under it. Cursor's CLI reads the same mcp.json.

opencode

Add a remote entry under mcp, either in opencode.json at the project root or in ~/.config/opencode/opencode.json to make it available everywhere:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alphasoc": {
      "type": "remote",
      "url": "https://api.alphasoc.net/mcp",
      "enabled": true,
      "oauth": {
        "clientId": "mcp-client",
        "redirectUri": "http://localhost:9876/callback",
        "scope": "openid api offline_access"
      }
    }
  }
}

All three oauth fields are required, and redirectUri must be given even though opencode would otherwise supply its own. opencode runs the OAuth flow the first time it connects. Use 9877 in redirectUri if port 9876 is already in use on your machine.

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect with the same settings: the endpoint above, mcp-client as the OAuth client ID, and, where the client asks for one, 9876 or 9877 as the callback port.

Verify the connection

Whatever the client, the check is the same. Ask:

Which AlphaSOC workspaces can you see?

If the agent lists your workspaces, with your role and licenses in each, the connection and sign-in both work.

The tools that read your data operate within a single workspace, so tell the agent which workspace you are working in ("in Production") and it uses that workspace for the rest of the conversation. If you belong to just one, it will find it on its own.

Available tools

Tool	What it does	License
`whoami`	Your identity and every workspace you can act in, with roles and licenses	—
`findings_summary`	Searchable summaries of findings by detection, MITRE technique, log source or observable	AE
`lake_search`	The raw records carrying an exact value, from Evidences, Activity or Events	AE
`wisdom_lookup`	AlphaSOC Wisdom threat intelligence for one domain or IP	Wisdom
`kql_search`	Whole raw rows and complex queries, one dataset at a time	AE
`kql_datasets`	The dataset schemas `kql_search` can be written against	—
`kql_guide`	The KQL reference documentation, for the agent's own use	—

Workspace-scoped tools require the Guest role or above, the same read access the console applies to findings. AE and Wisdom are licensed independently, per workspace, and only the product a tool reads has to be active; whoami shows where you stand on both.

For what each tool can do and how to drive it, see Findings & Telemetry and Threat Intelligence.

Limits

Tool calls are rate-limited per user, and wisdom_lookup more tightly than the rest, since its lookups are metered. Searches cover at most 90 days per call, never reach past a dataset's retention, and cap how much they return. The agent knows these limits and works within them; if it reports hitting one, narrow the question (see asking good questions).

Troubleshooting

Connecting

Symptom	Cause and fix
The client cannot connect at all	Confirm the transport is Streamable HTTP (not SSE) and the URL is exactly `https://api.alphasoc.net/mcp`.
An error about dynamic client registration	No client ID is configured. Add it: `--client-id` in Claude Code, `auth.CLIENT_ID` in Cursor, `oauth.clientId` in opencode.
An error about the redirect URI not matching	The callback is wrong or was left unset. In Claude Code and opencode use `9876` or `9877` exactly as shown above; Cursor needs no port. If it persists, report it to AlphaSOC support.
Browser login never completes	Check that pop-ups and redirects to `oauth.alphasoc.net` are not blocked, then retry the client's authenticate action.
Calls start failing after working fine	The grant expired or was revoked. Sign in again (`/mcp` in Claude Code).
A workspace you were just added to is missing	Your token covers the workspaces you belonged to when you signed in, and silent refreshes do not update that set. Re-run your client's authenticate step.
An SSO-only workspace is missing after re-authenticating	A workspace that enforces SSO sign-in is covered only when you sign in through that workspace's SSO provider. Authenticate again and sign in through it.
Only `whoami` appears in the tool list	The other surfaces are not enabled on your deployment. The tool list reflects what the server serves, not what you are licensed for.

Tool access and permissions

A refusal the agent reports usually names one of these:

Refusal	Cause and fix
`notConsented`	The workspace is not covered by your current sign-in. Sign in again; for an SSO-enforced workspace, sign in through its SSO provider.
`notAMember`	Your membership of that workspace was removed.
`licenseInactive`	No active license for the product the tool reads. AE and Wisdom are licensed separately; ask for `whoami` to see both.
`internal`	Not an access problem: the check itself could not be completed. Retry; signing in again will not help.

Setup​

Claude Code​

Claude.ai and Claude Desktop​

Cursor​

opencode​

Other clients​

Verify the connection​

Available tools​

Limits​

Troubleshooting​

Connecting​

Tool access and permissions​