# Connect your AI assistant to Jaws in 3 minutes

Source: https://www.jawsdeploy.net/guides/mcp-quickstart

Step-by-step setup for Claude Code, Claude Desktop, Cursor, Codex Desktop and Codex CLI. Use your existing AI subscription to drive Jaws: create projects, build deployment pipelines, read deployment logs, author step templates and set variables.

## 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](https://nodejs.org)), **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:**

```bash
echo -n 'YOUR_SERVICE_ACCOUNT_ID:YOUR_API_KEY' | base64
```

**Windows PowerShell:**

```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:

```bash
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](https://www.npmjs.com/package/mcp-remote) bridge in the config file. It needs [Node.js](https://nodejs.org): check with `node --version`.

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

**Windows:**

```json
{
  "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:**

```json
{
  "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:

```json
{
  "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`:

```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.

> **Next - See what the MCP server can do**
> 
> The [feature overview](https://www.jawsdeploy.net/features/mcp) covers what an assistant can do in Jaws and how the safety design works.