jam Skill | Agent Skills

Troubleshooting

If requests fail, run zero doctor check-connector --env-name JAM_TOKEN or zero doctor check-connector --url https://mcp.jam.dev/mcp --method POST

How to Use

Jam exposes its API through an MCP (Model Context Protocol) server at https://mcp.jam.dev/mcp. All interactions use JSON-RPC 2.0 over HTTP with Bearer token authentication. You need to initialize the MCP session first, then call tools.

Base URL

MCP endpoint: https://mcp.jam.dev/mcp

1. Initialize MCP Session

Start an MCP session to get a session URL for subsequent requests.

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"vm0","version":"1.0.0"}}}' -D /tmp/jam_headers.txt | jq .

After initialization, check the response headers for the Mcp-Session-Id or use the session URL from the response. Save the session URL for subsequent calls:

SESSION_URL=$(grep -i "location:" /tmp/jam_headers.txt | tr -d '\r' | awk '{print $2}')

If no redirect location is returned, use the same endpoint with the session ID from the response headers.

2. List Available Tools

Discover all available MCP tools.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq '.result.tools[] | {name, description}'

3. List Jams

Search and filter Jams in your workspace.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "listJams",
    "arguments": {}
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

Filter by text, type, folder, author, URL, or date:

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "listJams",
    "arguments": {
      "text": "login bug",
      "type": "recording"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

4. Get Jam Details

Get a quick snapshot of a Jam including who made it, what happened, and which tools to try next. Replace JAM_ID with the actual Jam identifier (the URL slug or ID from listJams).

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "getDetails",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

5. Get Console Logs

Retrieve console logs from a Jam session, filtered by log level and count.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "getConsoleLogs",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID",
      "logLevel": "error",
      "limit": 50
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

Available logLevel values: error, warn, info, log, debug.

6. Get Network Requests

List all HTTP requests captured during the Jam recording, with optional filters.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "getNetworkRequests",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID",
      "statusCode": 500,
      "limit": 20
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

Filter parameters: statusCode (HTTP status code), contentType (e.g., application/json), host (e.g., api.example.com), limit (max results).

7. Get User Events

Read user interactions including clicks, inputs, and page navigations in plain language.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "getUserEvents",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

8. Get Screenshots

Extract screenshots from screenshot-type Jams for visual inspection.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "getScreenshot",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

9. Get Video Transcript

Retrieve spoken captions from video Jams in WebVTT format with timestamps.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "getVideoTranscript",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

10. Analyze Video

Use AI-powered analysis on Jam video recordings to extract insights, detect issues, and get structured feedback.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "analyzeVideo",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

11. Get Custom Metadata

Access custom key-value metadata set via the jam.metadata() SDK in your application.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "getMetadata",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

12. List Folders

Browse available folders in your Jam workspace.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "listFolders",
    "arguments": {}
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

13. List Team Members

Browse team members in your Jam workspace.

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "listMembers",
    "arguments": {}
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

14. Add a Comment

Add a Markdown comment to a Jam recording (requires mcp:write scope).

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "createComment",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID",
      "comment": "Investigated this issue - the root cause is a race condition in the auth middleware."
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

15. Move a Jam to a Folder

Move a Jam to a different folder (requires mcp:write scope).

Write to /tmp/jam_request.json:

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "updateJam",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID",
      "folder": "Triaged Bugs"
    }
  }
}

Then run:

curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .

Guidelines

Initialize first: Always initialize an MCP session before calling tools. The session persists across multiple tool calls
Use temp files for JSON: Write JSON payloads to /tmp/jam_request.json to avoid shell quoting issues with nested JSON
Token scopes matter: mcp:read is sufficient for read operations (getDetails, getConsoleLogs, etc.). Use mcp:write only when you need to create comments or move Jams
Token expiration: PATs have mandatory expiration dates (7 days to 1 year). Plan for token rotation
Jam URLs: Most tools require a jamUrl parameter. Use the full URL format https://jam.dev/c/JAM_ID
Debugging workflow: Start with getDetails for an overview, then use getConsoleLogs (filter by error), getNetworkRequests (filter by 4xx/5xx status codes), and getUserEvents to build a complete picture
Rate limits: Jam enforces rate limits on their API. If you receive HTTP 429 responses, implement backoff
MCP protocol: All requests use JSON-RPC 2.0 format with method: "tools/call" and tool-specific arguments

Agent Skills: jam

Install this agent skill to your local

Skill Files

Troubleshooting

How to Use

Base URL

1. Initialize MCP Session

2. List Available Tools

3. List Jams

4. Get Jam Details

5. Get Console Logs

6. Get Network Requests

7. Get User Events

8. Get Screenshots

9. Get Video Transcript

10. Analyze Video

11. Get Custom Metadata

12. List Folders

13. List Team Members

14. Add a Comment

15. Move a Jam to a Folder

Guidelines