AI Agents (MCP Server)

What is the MCP Server?

FirmwareCI ships a Model Context Protocol (MCP) server that exposes your projects, workflows, DUTs, jobs, and test schemas to AI coding agents — Claude Code, Cursor, VS Code (GitHub Copilot), Codex, OpenCode, and any other MCP-capable client.

With it connected, an agent can answer questions about your test runs, help author and validate new tests against the real schemas, and walk you through onboarding — all from your editor or terminal, without you copying IDs and YAML back and forth.

Read-only. The current MCP server is strictly read-only. Agents can list, inspect, author, and validate, but cannot create, edit, delete, or trigger anything on the server.

Prerequisites

An MCP-capable AI client (see Enabling the Server).
A FirmwareCI organization API token.

Getting your token:

Log in to the FirmwareCI web UI.
Navigate to the settings page.
Open the tokens tab.
Create a user token, or ask your administrator if an org token is required.

The MCP server uses the same token as the CLI and CI/CD integrations. Every request is scoped to the token’s organization — agents never see data from other organizations.

Endpoint

https://api.firmware-ci.com/mcp

Transport: Streamable HTTP. Authentication: Authorization: Bearer <token> header.

Capabilities

Tools

All tools are read-only or pure functions. Pagination is page-based (page * limit = row offset); arguments are passed as strings. Every list tool returns has_more so you know when to stop paging.

Tool	Purpose
`fwci_list_workflows`	List workflows. Optional `name` (substring), `project_id`, `page`, `limit`.
`fwci_get_workflow`	Fetch a workflow by ULID.
`fwci_list_duts`	List Devices Under Test. Optional `name` (substring), `project_id`, `page`, `limit`.
`fwci_get_dut`	Fetch a DUT by ULID, with full attributes.
`fwci_list_projects`	List projects. Returns ULIDs usable as `project_id` elsewhere.
`fwci_list_jobs`	List jobs. Filter by `status` (comma-separated) and/or `workflow_id`; paginate with `page`/`limit`.
`fwci_get_job`	Fetch a job by ULID: status, test, DUT, timestamps, error.
`fwci_get_job_logs`	Per-step logs for a job. Tails running jobs.
`fwci_validate_test`	Validate a test definition (YAML/JSON) against the schemas. Returns `{valid: true}` or an error.
`fwci_validate`	Validate a non-test document by `kind` (`dut`, `dut-pre-post`, `workflow`, `storage`). Returns `valid` plus structured `issues` (`field` + `message`) on failure.
`fwci_list_schemas`	List schema names: `test`, `workflow`, `step:<cmd>`, `common:<name>`.
`fwci_get_schema`	Fetch one JSON Schema by name. Carries agent guidance and an inline YAML example.
`fwci_list_examples`	List canonical, schema-valid YAML examples shipped with the server.
`fwci_get_example`	Fetch one example by path.

Names (workflows, DUTs) are unique only within a project, so pass project_id alongside name when the same name may exist in more than one project.

Prompts

Pre-built conversation starters the client surfaces to you:

Prompt	Purpose
`bootstrap_workflow`	Onboard a user or agent to FirmwareCI.
`explain_failure`	Triage a failed job: pull logs, identify the failing step.
`convert_existing_ci`	Translate a GitHub Actions or GitLab CI config into a FirmwareCI test.

Resources

URI-addressable records, useful when an agent wants to quote or cite an entity without a tool call:

URI	Returns
`fwci://workflow/{id}`	Full workflow record (JSON).
`fwci://job/{id}`	Full job record (JSON).
`fwci://dut/{id}`	Full DUT record (JSON).
`fwci://docs/{+path}`	FirmwareCI documentation by path.

Enabling the Server

Each client stores MCP configuration differently. In every example below, replace <YOUR_TOKEN> with your FirmwareCI organization token. Keep configuration files that contain a literal token out of version control.

Claude Code

claude mcp add --transport http --scope user firmwareci \
  https://api.firmware-ci.com/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"

--scope user makes the server available in every project. Start a new session and run /mcp to confirm the connection.

Cursor

Add to ~/.cursor/mcp.json for all projects (or .cursor/mcp.json in a project root to scope it to that workspace):

{
  "mcpServers": {
    "firmwareci": {
      "url": "https://api.firmware-ci.com/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace (or your user profile via MCP: Open User Configuration). Note VS Code uses servers as the root key, and MCP tools are only available in Copilot’s Agent mode:

{
  "servers": {
    "firmwareci": {
      "type": "http",
      "url": "https://api.firmware-ci.com/mcp",
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

You can also add it interactively: open the Command Palette (Ctrl+Shift+P), run MCP: Add Server, and choose HTTP.

Codex

Add to ~/.codex/config.toml. Codex reads the token from an environment variable, so the secret stays out of the file:

[mcp_servers.firmwareci]
url = "https://api.firmware-ci.com/mcp"
bearer_token_env_var = "FWCI_TOKEN"

Export the token in your shell before starting Codex:

export FWCI_TOKEN="<YOUR_TOKEN>"

If your Codex build does not connect over streamable HTTP, add experimental_use_rmcp_client = true to the server table.

OpenCode

Add to your global config at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "firmwareci": {
      "type": "remote",
      "url": "https://api.firmware-ci.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
    }
  }
}

Other clients

Using a different MCP client? Consult that tool’s own MCP documentation for how to register a server — support and configuration formats vary by client. You only need three things, which every MCP-capable client accepts in some form:

Transport: Streamable HTTP (sometimes labelled “remote” or “http”).
URL: https://api.firmware-ci.com/mcp
Header: Authorization: Bearer <YOUR_TOKEN>

Trying It Out

Once connected, ask your agent questions in natural language. The agent selects the right tools on its own:

“List my last 5 FirmwareCI jobs.”
“Find the failed jobs for workflow <ULID> and show me the failing step’s logs.”
“Which workflow is named ‘Boot Test’?” (uses the name filter)
“What test step schemas are available?”
“Write a FirmwareCI test that pings the DUT, then validate it.”
“Write a DUT pre-stage that flashes firmware, then validate it as a dut-pre-post.”
“Help me onboard to FirmwareCI.”

Limitations

Read-only. No job creation, abort, or edits. Authoring happens locally (your agent writes files); the server only reads and validates.
One organization per token. A user belonging to multiple organizations needs a separate token per organization.
Rate limited per organization. Responses include X-Ratelimit-* headers; clients should back off on 429.