What is Devs.Surf MCP Server?

The Model Context Protocol (MCP) is the open standard developed by Anthropic that allows AI agents to securely interact with external systems, tools, and data stores.

Devs.Surf MCP Server connects your AI coding agents directly to our domain and DNS orchestration engine. Instead of opening a web browser to register subdomains and copy-paste DNS records, your AI assistant can:

Check if a subdomain like vibe-project.devs.surf is available.
Claim and provision the subdomain instantly for your account.
Create CNAME, A, AAAA, and TXT records pointing to Vercel, Netlify, Railway, or VPS.
Inspect and audit existing records without leaving your IDE or terminal.

02

1-Minute Quickstart (Auto-Installer)

Run the official installer in your terminal. It detects your installed AI apps (Claude Desktop and Claude Code CLI), writes the configuration files automatically, and launches your browser to authenticate via OAuth 2.0 PKCE:

npx -y --package=https://devs.surf/mcp/devs-surf-mcp-1.2.0.tgz devs-surf-mcp install

Step 1

Installer registers MCP server into Claude Desktop and Claude Code configuration.

Step 2

Browser opens devs.surf with secure S256 PKCE challenge. Click "Authorize".

Step 3

Token is saved securely in your home directory (~/.devssurf/token.json). You are ready.

03

Supported AI Clients & Manual Setup

Claude Desktop

macOS / Windows / Linux

Config file path:
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "devs-surf": {
      "command": "npx",
      "args": [
        "-y",
        "--package=https://devs.surf/mcp/devs-surf-mcp.tgz",
        "devs-surf-mcp"
      ]
    }
  }
}

Claude Code CLI

Terminal / Headless

Add the MCP server directly via Claude Code CLI command:

claude mcp add devs-surf -- npx -y --package=https://devs.surf/mcp/devs-surf-mcp.tgz devs-surf-mcp

Verify with: claude mcp list

Cursor & Windsurf

Project-level or Global MCP

Add to your project's .cursor/mcp.json or Cursor Settings > MCP:

{
  "mcpServers": {
    "devs-surf": {
      "command": "npx",
      "args": ["-y", "--package=https://devs.surf/mcp/devs-surf-mcp.tgz", "devs-surf-mcp"]
    }
  }
}

Cloud Agents & Web (SSE Transport)

Remote MCP Endpoint

For agents running in Docker, CI/CD, or cloud platforms without local stdio:

{
  "mcpServers": {
    "devs-surf": {
      "url": "https://devs.surf/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_DEVS_SURF_API_TOKEN"
      }
    }
  }
}

04

Authentication Flow

Devs.Surf MCP server supports two secure authentication modes:

Mode 1: Interactive OAuth 2.0 PKCE

Recommended for developer workstations. Uses a temporary local HTTP loopback server on port 50445 with SHA-256 code challenge. No manual token copying required.

Command: devs-surf-mcp --login

Mode 2: Scoped API Token

Recommended for CI/CD, Docker containers, remote servers, or headless scripts. Generate a token in Dashboard with custom permissions and inject it via environment variable.

Env var: DEVS_SURF_API_TOKEN=...

Session tokens are saved to ~/.devssurf/token.json with file permissions restricted to your local operating system user.

05

Tool Reference (13 Tools)

The MCP server exposes 13 strongly-typed JSON-RPC tools to Claude and other LLM agents:

check_domain_availability Public (No Auth Required)

Check whether a specific subdomain is available to claim on Devs.Surf.

Arguments:
subdomain (string, required): Subdomain name to test (e.g. "my-project").

claim_domain Authenticated

Claim and register an available subdomain under your account in real time.

Arguments:
domain or label (string, required): The target subdomain (e.g. "my-project" or "my-project.devs.surf").

list_domains Authenticated

List all active subdomains owned by your authenticated account.

Arguments: None.

list_dns_records Authenticated

Retrieve all active DNS records (A, AAAA, CNAME, TXT) for a specified domain you own.

Arguments:
domain (string, required): The domain name (e.g. "my-project.devs.surf").

add_dns_record Authenticated

Add a new DNS record to your subdomain.

Arguments:
domain (string, required): Target domain.
type (string, required): Record type (A, AAAA, CNAME, TXT).
name (string, required): Record host name (use @ for apex or subdomain prefix like api).
content (string, required): Target value (e.g. IP address or CNAME target).
ttl (integer, optional): Time-to-live in seconds (default: 60).

delete_dns_record Authenticated

Remove an existing DNS record from your domain.

Arguments:
domain (string, required): Target domain.
record_id (string|integer, required): ID of the DNS record.

delete_domain Authenticated

Release and delete a subdomain from your account.

Arguments:
domain (string, required): Domain name to delete.

get_account_info Authenticated

Get current user email, tier, domain quota, and active limits.

Arguments: None.

Session Management Tools Local Helpers

Client-side session management helpers inside the MCP runtime:

check_auth_status: Verifies if a valid session exists.
login: Triggers OAuth 2.0 PKCE browser login.
logout: Clears local cached tokens.
set_api_token: Sets a static API token directly.

06

Example AI Prompts (Vibe Coding)

Once installed, you do not need to specify commands. Just prompt Claude or your AI agent naturally:

Prompt: Claim Domain & Point to Vercel

"Check if `acme-shop` is available on devs.surf. If available, claim it for me and set a CNAME record pointing to `cname.vercel-dns.com`."

Prompt: Configure VPS Server DNS

"List my devs.surf domains. For `my-api.devs.surf`, add an A record pointing to my VPS IP `142.93.120.45` with TTL 60 seconds."

Prompt: Audit & Verify Records

"Inspect all DNS records for `tablerelay.devs.surf` and tell me if there are any conflicting CNAME and A records."

07

Security & Tenant Guard

Devs.Surf enforces strict zero-trust tenant boundaries across all MCP and API endpoints:

Strict Ownership Binding

Every DNS lookup, addition, and deletion checks domain ownership against the user ID bound to the token. Cross-tenant access returns 404.

SHA-256 Token Storage

Plaintext tokens are never stored in the database. Tokens are hashed with SHA-256 and verified deterministically.

Safe Outbound Policy

Subdomains cannot add arbitrary outbound mail records (MX/SPF/DKIM) without administrative whitelist approval, preventing spam abuse.

Instant Revocation

Tokens can be revoked immediately from the user dashboard without impacting other active sessions.

08

Troubleshooting & FAQ

Why does npx show "connected via stdio" and wait?

Stdio mode is designed for Claude Desktop to communicate via JSON-RPC over standard input/output. For interactive setup or status inspection, make sure to append the subcommand:
devs-surf-mcp install or devs-surf-mcp --status.

How do I check if Claude Desktop sees the MCP tools?

In Claude Desktop, click on the plug icon in the chat input or go to Settings > MCP. You will see devs-surf listed with a green indicator and 13 registered tools.

How do I log out or switch accounts?

Run:
npx -y --package=https://devs.surf/mcp/devs-surf-mcp-1.2.0.tgz devs-surf-mcp --logout
Then run devs-surf-mcp install again to authenticate with your other account.