MCP quickstart

Before you start

You need:

• Workspace Full Control on at least one Jaws workspace. Every plan includes the MCP server.
• An AI client: Claude Code, Claude Desktop (which also needs Node.js), Cursor, Codex Desktop or Codex CLI. Any other MCP client works too if it can connect to a remote Streamable HTTP server and send a custom Authorization header.

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 an MCP account in Jaws

The quickest route is the setup page built into Jaws:

1. Open Settings → AI assistants and click Create MCP account.
2. Choose a workspace. The assistant can only access this workspace.
3. Click your AI assistant. Jaws creates a service account named MCP: <assistant> (<your name>, <date and time> UTC), gives it Workspace Full Control on the chosen workspace and generates an API key.
4. Copy the API key. It is shown once and cannot be retrieved later.

The page then shows the setup for your assistant with your credentials already filled in: a terminal command, a config snippet to paste, or the values to type into a form. Follow it and go to step 05.

Your MCP accounts are listed under Settings → AI assistants → Manage MCP accounts, where you can also get the setup instructions again or delete an account.

Why a separate account? The assistant gets only the access you give that account, you can revoke it without touching your own login, and its changes are made as that account, not as you.

Or: set up the credentials by hand

Skip this step if you used the setup page in step 02.

1. Open Settings → Service accounts and create a service account.
2. Give it a role with Workspace Full Control on each workspace the assistant should work in. MCP tools only work on workspaces the account can manage.
3. Create an API key for it. Copy the service account ID and the key.
4. Build the Authorization header. The MCP server uses HTTP Basic auth: Base64-encode serviceAccountId:apiKey and put Basic in front.

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 header value is Basic <output>. In the snippets below, replace YOUR_BASE64_HERE with the output.

Configure your AI client

The server URL is https://app.jawsdeploy.net/mcp. On self-hosted Jaws Stack, use your own host instead: https://<your-jaws-host>/mcp.

Claude Code

Run in a terminal:

claude mcp add --transport http --scope user jaws https://app.jawsdeploy.net/mcp --header "Authorization: Basic YOUR_BASE64_HERE"

--scope user makes the server available in all your projects. Start Claude Code and run /mcp: jaws should show as connected.

Claude Desktop

Claude Desktop's Connectors screen only supports servers that sign in with OAuth, so Jaws is added through the mcp-remote bridge in the config file. It needs Node.js: check with node --version.

Open Settings → Developer → Edit Config to open claude_desktop_config.json and add the jaws entry under mcpServers.

Windows:

{
  "mcpServers": {
    "jaws": {
      "command": "cmd",
      "args": [
        "/c", "npx", "mcp-remote",
        "https://app.jawsdeploy.net/mcp",
        "--header",
        "Authorization:${JAWS_AUTH}"
      ],
      "env": {
        "JAWS_AUTH": "Basic YOUR_BASE64_HERE"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "jaws": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.jawsdeploy.net/mcp",
        "--header",
        "Authorization:${JAWS_AUTH}"
      ],
      "env": {
        "JAWS_AUTH": "Basic YOUR_BASE64_HERE"
      }
    }
  }
}

Keep Authorization:${JAWS_AUTH} exactly as written, with no space after the colon. The header value goes in env because some clients split arguments that contain spaces. Quit Claude Desktop completely and reopen it after saving.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project root:

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

If you used the setup page in Jaws, its Install in Cursor button adds this for you.

Codex Desktop

1. Open Settings → MCP servers → Add server.
2. Choose Streamable HTTP.
3. Enter the name jaws, the URL https://app.jawsdeploy.net/mcp and a header with key Authorization and value Basic YOUR_BASE64_HERE.
4. Click Save, then Restart.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.jaws]
url = "https://app.jawsdeploy.net/mcp"
http_headers = { "Authorization" = "Basic YOUR_BASE64_HERE" }

Other MCP clients

Add a remote MCP server that uses the Streamable HTTP transport, with the URL https://app.jawsdeploy.net/mcp and the header Authorization: Basic YOUR_BASE64_HERE. Your client's documentation says where these go.

Verify the connection

In your AI client, type:

Use the Jaws MCP server's whoami tool.

The answer includes "connected": true, your organization ID and workspaceCount, the number of workspaces this account can manage. An account made on the setup page has exactly one.

If the client reports an authentication error (HTTP 401):

• check that the header value starts with Basic and the Base64 part has no extra spaces or line breaks
• check that the service account and its API key still exist and the key has not expired
• check that the URL ends in /mcp

For Claude Desktop, also check that node --version works in a terminal.

What to try first

1. Tour your workspace: List my Jaws workspaces, then list the projects in the first one.

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". 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 my 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

• Deploying takes a preview first. preview_deploy is a dry run: it shows which steps run on which machines and returns a confirmation token that lasts two minutes. trigger_deploy only accepts that token, and its instructions tell the assistant to wait for your explicit go-ahead.
• No secret values in the conversation. list_variables returns Secret values masked as ***, and set_variable and set_variable_value reject Secret variables. You set secrets in the Jaws UI.
• Only what the service account can manage. Every tool checks the account's workspace permissions, the same way the REST API does.
• Revocation within a minute. Delete the MCP account, or its API key, and the assistant loses access within a minute.