MCP quickstart

Before you start

You need:

• A Jaws workspace you can manage. Every plan includes the MCP server.
• An MCP-aware AI client:

- Claude Code (v1.0+) - Claude Desktop (1.0+, HTTP MCP) - Cursor (0.42+) - Codex Desktop (Streamable HTTP) - Codex CLI ([mcp_servers] support) - Continue (v0.9.200+) - Anything that follows the MCP spec

• Five minutes.

You do not need an Anthropic, OpenAI, or any other AI API key on the Jaws side. Your AI client uses your existing subscription.

Create a Jaws service account

1. In Jaws, open your workspace → Settings → Service Accounts. 2. Click New service account. Name it something like mcp-claude-code — this name appears in audit logs. 3. Grant the service account the workspace permissions you want the AI to have. Workspace: Full control is the simplest starting point — scope it down later. 4. Generate an API key. Copy both the service account ID and the API key — you'll need both in the next step. The key is shown once — regenerate if lost.

> Why a service account? Scoped permissions, independent revocation, and clear audit-log attribution — the AI's actions show as coming from this account, not your personal login.

Build the Authorization header

The MCP server uses HTTP Basic auth. Base64-encode serviceAccountId:apiKey and prepend Basic .

macOS / Linux:

echo -n 'YOUR_SERVICE_ACCOUNT_ID:YOUR_API_KEY' | base64

Windows PowerShell:

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('YOUR_SERVICE_ACCOUNT_ID:YOUR_API_KEY'))

The result is your Authorization header value: Basic <output>.

Configure your AI client

Adjust the URL if you are on self-hosted Jaws Stack.

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "jaws": {
      "type": "http",
      "url": "https://app.jawsdeploy.net/mcp",
      "headers": { "Authorization": "Basic YOUR_BASE64_HERE" }
    }
  }
}

Restart Claude Code. Run /mcp to confirm jaws is listed.

Claude Desktop

Open Settings → Developer → Edit Config, add the same jaws block under mcpServers, restart.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "jaws": {
      "url": "https://app.jawsdeploy.net/mcp",
      "headers": { "Authorization": "Basic YOUR_BASE64_HERE" }
    }
  }
}

Codex Desktop

Open Settings → MCP servers → Add server, switch to Streamable HTTP, enter the URL and the Authorization header.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.jaws]
url = "https://app.jawsdeploy.net/mcp"

[mcp_servers.jaws.headers]
Authorization = "Basic YOUR_BASE64_HERE"

Continue

Add to ~/.continue/config.json under experimental.modelContextProtocolServers:

[{ "transport": { "type": "http", "url": "https://app.jawsdeploy.net/mcp", "headers": { "Authorization": "Basic YOUR_BASE64_HERE" } } }]

Verify the connection

In your AI client, type:

> Use the Jaws MCP server's whoami tool.

Expected response:

{
  "serviceAccountId": "sa_01HXXX...",
  "organizationId": "org_01HXXX...",
  "workspaceCount": 3,
  "connected": true
}

If connected: true and workspaceCount matches, you're done. If you get an auth error: check the base64 has no extra whitespace, the service account is active, and the URL ends in /mcp.

What to try first

1. Tour your workspace: > List my Jaws workspaces, then pick the production one and list its projects.

2. Diagnose a failure: > Find the most recent failed deployment in my workspace and explain what went wrong.

3. Build a new pipeline: > Create a project called "deploy-api" in workspace ID. Add a step that downloads an artifact zip and copies it to the deploy folder.

4. Author a step template: > Create a step template called "Wait for healthy" that pings an HTTP endpoint until it returns 200 or 2 minutes pass.

5. Set variables in bulk: > Set API_BASE_URL, LOG_LEVEL, and FEATURE_FLAGS in the staging workspace.

6. Organise by conversation: > Create a folder called "Staging" and move all projects whose names contain "staging" into it.

What the AI can and can't do

• No deploy triggers without a preview. trigger_deploy only accepts a short-lived token from preview_deploy. You always see the dry-run first.
• No secrets written or read in plaintext. set_variable rejects Secret type. list_variables masks Secret values as ***.
• Only what the service account can see. Permissions are checked on every call via the same WorkspaceGuard as the REST API.
• Instant revocation. Delete or disable the service account and the AI loses access immediately.