Socket MCP Server

Add the hosted server through Claude's custom connector settings. The Developer configuration file is for local servers.

1. Open Customize > Connectors in Claude.
2. Select Add custom connector and enter https://mcp.socket.dev/ as the server URL. On Team and Enterprise plans, an organization owner adds the connector through Organization settings > Connectors first.
3. Select Connect and complete the Socket authorization flow when prompted.
4. Enable the connector for your conversation, then ask Claude "Check the security score for express version 4.18.2".

For Claude Code, one command does all of it:

claude mcp add --transport http socket-mcp https://mcp.socket.dev/

# For VS Code with GitHub Copilot
code --add-mcp '{"name":"socket-mcp","type":"http","url":"https://mcp.socket.dev/"}'

Or add to .vscode/mcp.json:

{
  "servers": {
    "socket-mcp": {
      "type": "http",
      "url": "https://mcp.socket.dev/"
    }
  }
}

Cursor Settings → MCP → Add new MCP Server. Name socket-mcp, http type, URL https://mcp.socket.dev/.

{
  "mcpServers": {
    "socket-mcp": {
      "type": "http",
      "url": "https://mcp.socket.dev/"
    }
  }
}

Windsurf does not support http type MCP servers. Use the stdio configuration in Option 2 below, or the serverUrl form:

{
  "mcpServers": {
    "socket-mcp": {
      "serverUrl": "https://mcp.socket.dev/mcp"
    }
  }
}

Factory is an AI-powered software engineering platform. Install the Socket MCP server with the Factory CLI:

droid mcp add socket https://mcp.socket.dev/ --type http

To self-host with an API key instead, see Option 2 below and register the stdio command with droid mcp add.

Alternatively, type /mcp within the Factory droid to manage MCP servers from an interactive UI. Learn more in the Factory MCP documentation.

Claude Code:

claude mcp add socket-mcp -e SOCKET_API_TOKEN="your-api-token-here" -- socket-mcp

Most other MCP clients:

{
  "mcpServers": {
    "socket-mcp": {
      "command": "socket-mcp",
      "env": {
        "SOCKET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Run the server in HTTP mode:

MCP_HTTP_MODE=true SOCKET_API_TOKEN=your-api-token socket-mcp --http

The server listens on http://localhost:3000/. The MCP endpoint is / and the health endpoint is /health; every other path answers 404.

The transport is stateless. Each POST / is self-contained, with no session to open, no Mcp-Session-Id header, and nothing to expire, so you can put several instances behind a load balancer without session affinity. GET and DELETE on the MCP endpoint answer 405. Clients written against the 2025 protocol, which open with an initialize handshake, are still served.

Environment variables for HTTP mode:

The three OAuth variables are a set: configure all three or none. Setting only some of them makes the server print Incomplete OAuth configuration for HTTP mode and exit 1, rather than quietly start unauthenticated.

SOCKET_API_TOKEN is canonical. These aliases are read in order, first non-empty wins: SOCKET_API_TOKEN, SOCKET_API_KEY, SOCKET_CLI_API_TOKEN, SOCKET_CLI_API_KEY, SOCKET_SECURITY_API_TOKEN, SOCKET_SECURITY_API_KEY.

SOCKET_API_TOKEN, SOCKET_API_BASE_URL, and SOCKET_DEBUG also apply in stdio mode. Everything else in the table is HTTP-only.

Enabling OAuth. Set all three OAuth variables to require an OAuth access token on every MCP request:

MCP_HTTP_MODE=true \
SOCKET_OAUTH_ISSUER=https://issuer.example.com \
SOCKET_OAUTH_INTROSPECTION_CLIENT_ID=your-client-id \
SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret \
socket-mcp --http

With OAuth enabled, every request to the MCP endpoint goes through RFC 7662 token introspection. A raw Socket API token is rejected with a 401, whatever its prefix; a sktsec_ token is no more privileged than any other string here. Callers send an OAuth access token, and the server uses that token for the Socket API calls it makes on their behalf. Run without the OAuth variables to accept raw Socket API tokens instead.

At startup the server discovers the issuer's RFC 8414 metadata. An issuer that carries a path (https://auth.example.com/tenant1) is probed at the path-inserted well-known URL first (https://auth.example.com/.well-known/oauth-authorization-server/tenant1), and the metadata document's own issuer must match SOCKET_OAUTH_ISSUER byte for byte. The issuer must be https on a public host; a loopback or private-network issuer is refused outright unless SOCKET_DEBUG=true is set for local-stack work. The same rule applies to the introspection_endpoint the metadata advertises.

Clients discover how to authenticate from GET /.well-known/oauth-protected-resource (RFC 9728), which the server publishes once OAuth is on:

{
  "resource": "https://mcp.example.com/",
  "authorization_servers": ["https://issuer.example.com"],
  "scopes_supported": ["packages:list"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Socket MCP Server"
}

A rejected request answers 401 with a WWW-Authenticate header naming that metadata URL and the scopes this resource requires:

WWW-Authenticate: Bearer error="invalid_token", error_description="Invalid or expired token",
  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="packages:list"

[!IMPORTANT] Audience validation. When an introspection response includes an aud claim, the server requires it to name this resource and rejects the token otherwise. That check is always on and has no opt-out. When the response includes no aud at all, the token is accepted by default, because an authorization server that never emits the claim would otherwise fail every request. Audience validation therefore protects you exactly as far as your authorization server populates aud; if it does not, no audience is being checked. Set SOCKET_OAUTH_REQUIRE_AUDIENCE=true to additionally require the claim's presence, but only once you have confirmed your authorization server returns aud on introspection. Enabling it against a server that omits the claim rejects all traffic.

Add TRUST_PROXY=true only when the server is deployed behind a trusted reverse proxy or load balancer that normalizes the forwarded host and protocol headers.

Configure your MCP client to connect to the HTTP server:

{
  "mcpServers": {
    "socket-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

depscore

Query the Socket API for dependency scoring information. Returns supply chain, quality, maintenance, vulnerability, and license scores per package.

Supported ecosystems

Based on Socket's language support. The ecosystem parameter maps to PURL types:

packagist is accepted as an alias for composer, and openvsx for the vscode PURL type.

Example request:

{
  "packages": [
    { "ecosystem": "npm", "depname": "express", "version": "4.18.2" },
    { "ecosystem": "pypi", "depname": "fastapi", "version": "0.100.0" }
  ]
}

Response, as a single block of text. Every score is an integer from 0 to 100, higher is better:

Dependency scores:
pkg:npm/[email protected]: license: 100, maintenance: 87, quality: 100, supplyChain: 97, vulnerability: 98
  Report: https://socket.dev/npm/package/express
pkg:pypi/[email protected]: license: 100, maintenance: 100, quality: 100, supplyChain: 100, vulnerability: 100
  Report: https://socket.dev/pypi/package/fastapi

Packages come back in the order the API returns them, not the order you asked for. A package Socket has no record of is left out of the list rather than reported as an error, so compare the response against your request when a name is missing.

organizations

List the Socket organizations the authenticated user belongs to. Takes no parameters. Use it to discover the org_slug value that the org-scoped tools (alerts, threat_feed) require.

This tool needs a Socket API token. See Authentication for organization-scoped tools below.

The response is the Socket API's JSON, keyed by organization id. The slug is what the other tools want:

{
  "organizations": {
    "1234": {
      "id": "1234",
      "name": "Acme Robotics",
      "plan": "enterprise",
      "slug": "acme-robotics"
    }
  }
}

alerts

List the latest security alerts for one Socket organization: supply-chain, vulnerability, quality, license, and maintenance issues across the org's monitored packages. Backed by GET /v0/orgs/{org_slug}/alerts. Results are paginated; pass the previous response's endCursor as cursor to fetch the next page.

threat_feed

Look up items in a Socket organization's threat feed: packages recently flagged as malware, typosquats, obfuscated code, and similar. Backed by GET /v0/orgs/{org_slug}/threat-feed. The response carries a nextPageCursor; pass it as cursor to page forward.

package_files

List the files published in a package: a tree of file paths, each with its size and blob hash, for any package on a supported ecosystem. Use it to inspect what a dependency ships before installing it. Pass a file's hash to package_file_contents or package_file_grep.

Output is a header line and a tree. The token after each size is the blob hash:

pkg:npm/[email protected] — 1054 files, 1379.3 KB
└── package/
    ├── fp/
    │   ├── __.js  43B  QlKUJ6782LHNEISw-t4uX1hyH1TCZye4ShYOMIAghheg
    │   ├── _baseConvert.js  16.0K  QpGkoQltpQn5ZeTFxYQOnk8FWp-7yyeUQtyzdZXl48nA

package_file_contents

Read a single file from a package. Pass the hash printed next to an entry in package_files output. Returns up to 1 MB of UTF-8 text; binary files return metadata only.

package_file_grep

Search a single file from a package for lines matching a JavaScript regular expression, returning matches with line numbers (grep -n style). Each blob is fetched once and held in a process-wide cache, so repeated reads and greps of the same hash skip the network.

Prerequisites: Node.js 24+.

1. Copy the whole dist/socket-gate directory into your hooks folder. The bundled socket-gate.cjs is self-contained, so it runs without any dependencies beside it.

   From a published install:

   mkdir -p ~/.claude/hooks
   cp -R node_modules/@socketsecurity/mcp/dist/socket-gate ~/.claude/hooks/
   

   From a checkout, build it first:

   pnpm run build
   mkdir -p ~/.claude/hooks
   cp -R dist/socket-gate ~/.claude/hooks/
   

2. Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/socket-gate/socket-gate.cjs"
          }
        ]
      }
    ]
  }
}

See hooks/socket-gate/README.md for the full reference.

This repo uses pnpm, and every command runs from the repo root. Node.js 24+ is required.

git clone https://github.com/SocketDev/socket-mcp.git
cd socket-mcp
pnpm install

Run from source. No build step is needed, because Node 24 strips the TypeScript itself:

export SOCKET_API_TOKEN=your_api_token_here
pnpm run server-stdio

Or in HTTP mode:

pnpm run server-http

Both scripts read SOCKET_API_TOKEN (falling back to SOCKET_API_KEY) from your environment. Append :debug to either one (pnpm run server-http:debug) to set SOCKET_DEBUG=1 and get per-request tracing on stderr.

Never put -- before a test path; that widens the run to the whole suite. Write pnpm test test/repo/unit/purl.test.mts.

To drive a running server by hand, see mock-client debugging.

Health check endpoint

When running in HTTP mode, GET /health returns the running server's version and skips origin validation, which makes it safe to call from a probe that sends no Origin header:

{
  "status": "healthy",
  "service": "socket-mcp",
  "version": "0.0.20",
  "timestamp": "2026-07-29T01:50:30.394Z"
}

Suitable for Kubernetes liveness/readiness probes, Docker health checks, load balancers.

Troubleshooting

Q: The public server isn't responding - Check the URL https://mcp.socket.dev/, verify your MCP client configuration, restart your MCP client.

Q: Getting a 403 Forbidden: Invalid origin error, or the connector never opens an OAuth screen - The server accepts client Origin headers when the request's Host matches the hosted deployment. Confirm that your client uses https://mcp.socket.dev/ and follows its setup steps above. A persistent Invalid origin response requires checking that the hosted deployment includes the fix.

Q: Local server fails to start - Ensure Node.js 24+ is installed, check SOCKET_API_TOKEN is set, verify the API token has packages:list permission. In stdio mode a missing token is fatal: the server prints SOCKET_API_TOKEN environment variable is required in stdio mode and exits 1.

Q: The server exits with Incomplete OAuth configuration for HTTP mode - SOCKET_OAUTH_ISSUER, SOCKET_OAUTH_INTROSPECTION_CLIENT_ID, and SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET must all be set or all be unset.

Q: Getting authentication errors with local server - Double-check your API key is valid, ensure packages:list scope, regenerate if needed. If the tool that failed was organizations, alerts, threat_feed, or package_files on an HTTP deployment, the server is refusing to answer with the operator's token by design; send your own in an Authorization: Bearer header.

Q: AI assistant can't find the depscore tool - Restart your MCP client after configuration changes, verify config is saved, check the server is running. tools/list advertises a one-hour public cache, so a client that caches the tool list may need a restart to pick up a newly added tool.

Getting help

• 📖 Socket Documentation
• 🐛 Report Issues
• 💬 Community Support