Skip to main content
Glama
Zephyr Squad MCP Server

Zephyr Squad MCP Server

Zephyr-Jira MCP + AI Agent Layer

A standalone, self-hosted Model Context Protocol (MCP) project with two layers:

  1. Atomic tool server (zephyr_mcp_server.py) — exposes Jira and Zephyr Scale test-management operations as MCP tools an AI assistant (Claude, Cursor, Windsurf, Devin, or any MCP-compatible client) can call directly: create test cases, link them to stories, audit test cycles, generate coverage reports.

  2. AI agent layer (zephyr_agent_server.py + zephyr_agent.py) — an independent MCP server and CLI that hand whole multi-step workflows to an LLM-driven agent ("generate test cases for this story, add steps, link them, and report") using your own provider — Anthropic, OpenAI, Azure OpenAI, or any OpenAI-compatible internal gateway.


Background

Organizations spend significant time creating and managing test assets across the software development lifecycle. Developers, QA engineers, and product teams routinely need to create test cases, document test steps, link tests to Jira stories, and organize them into test cycles. These activities are typically performed manually through the Jira and Zephyr UIs, which makes the process repetitive, time-consuming, and prone to inconsistency — especially during sprint planning, feature delivery, and release testing.

To address this, this project lets an AI assistant interact directly with Jira and Zephyr through natural language. Instead of navigating multiple screens and manually entering data, you describe what you want in plain English and the assistant performs the required actions. The atomic tool server covers single operations; the agent layer goes further and orchestrates entire workflows — plan → create → link → audit → report — in one instruction.

Related MCP server: JIRA Zephyr MCP Server

Problem Statement

There are now hundreds of community and vendor MCP servers available for Jira, Zephyr, and other QA/test-management tools. In practice, almost none of them are usable inside a bank, insurer, or other regulated enterprise environment, because they typically:

  • Route data through a third-party proxy or SaaS backend that the security team has no visibility into or control over.

  • Risk data leakage — test data, defect descriptions, and Jira issue content routinely contain confidential project, customer, or infrastructure details that cannot leave the corporate network.

  • Require broad, unscoped credentials (personal API tokens pasted into config files, no secret rotation, no audit trail).

  • Fail enterprise security review outright, because the vendor cannot show where the server runs, where the token is stored, or what egress the tool makes.

Why Not the Official Atlassian MCP Server?

Reason

Detail

Cloud-only

mcp.atlassian.com only connects to Atlassian Cloud instances (e.g. yourcompany.atlassian.net).

Private/on-premise blocked

Our Jira instance, https://jira.yourcompany.net, is a self-hosted, on-premise, corporate deployment. The cloud MCP endpoint cannot reach it.

No Zephyr support

Even on Cloud, the Atlassian MCP covers only native Jira/Confluence APIs. Zephyr is a third-party plugin with its own separate REST API that isn't exposed by the Atlassian MCP.

No Zephyr API access

The Atlassian MCP has no knowledge of Zephyr's test case, test step, test cycle, or execution endpoints.

Conclusion: the official Atlassian MCP server is structurally incompatible with this setup — both because of on-premise hosting and because Zephyr is outside its scope. Hence, this custom MCP project.

Design Principles

  • Standalone, self-hosted. Both servers run entirely inside your own network (or your own machine) as local processes. There is no external SaaS component, no vendor cloud, and no data ever leaves your environment unless your own Jira instance — or your own chosen LLM endpoint — is reached.

  • Your Jira, your rules. The Jira base URL is a configuration value you set yourself, e.g. https://jira.yourcompany.net — the server talks directly to your Jira/Zephyr instance over your existing network path (VPN, internal DNS, corporate proxy — whatever your organization already enforces). No requests go anywhere else.

  • Your LLM, your rules. The agent layer is provider-agnostic: one [llm] block in config.toml points it at Anthropic, OpenAI, Azure OpenAI, or an internal OpenAI-compatible gateway (LiteLLM, vLLM, Ollama). Choose an internal endpoint and LLM traffic stays inside the same boundary as Jira traffic.

  • No secrets in code or config files. API tokens are never hardcoded and never committed. They resolve at runtime from Azure Key Vault, or from environment variables / a gitignored .env file (see .env.example), so credential storage and rotation stay owned by your existing secrets-management infrastructure.

  • Least-surface footprint. The servers only implement the operations they explicitly expose as tools — there is no generic proxy, no arbitrary API pass-through, and no catch-all "run any REST call" tool. Mutating agent actions are approval-gated, and delete_test_case is hidden unless explicitly enabled.

  • Transparent and auditable. Every tool call is logged locally (zephyr_mcp.log, zephyr_agent.log) with the acting user, action, and target issue/project — giving you a local audit trail independent of Jira's own logs.

  • Fail loud at startup. validate_config() runs when either server or the CLI boots — a missing base URL, non-HTTPS Jira, or missing/placeholder token exits immediately instead of failing mid-task.

What It Does

The tool server wraps zephyr_client.py (a thin client over the Jira and Zephyr Scale REST APIs) and exposes each operation as an MCP tool. The agent server then orchestrates those tools with an LLM for multi-step work. Once connected to an MCP client, an assistant can:

Category

Tools

Resolution

Resolve project keys, issue keys, and issue types to their underlying Jira IDs

Test case management

Create, bulk-create, list, and delete Zephyr test cases; discover custom field IDs per project

Test design

Read and write test steps in Step-by-Step, BDD/Gherkin, or plain-text format

Linking & collaboration

Link tests to stories/bugs/epics; add comments to any Jira issue

Test cycles & execution

Fetch test cycles, execution results, and per-cycle pass/fail summaries; audit a cycle for missing attachments or unresolved statuses

Coverage & reporting

Report test coverage against stories/bugs in a project or sprint; generate aggregate pass/fail summaries

Jira queries

Fetch any issue by key; run arbitrary JQL searches

The agent layer adds workflow-level operations on top: run_workflow, cover_story, audit_sprint, release_report, list_workflows — plus the run_agent() function and zephyr_agent.py CLI for free-form instructions.

Architecture

flowchart TD
    A["MCP Client<br/>Claude Desktop, coding agents, etc."]
    F["CLI / run_agent()<br/>zephyr_agent.py"]
    G["zephyr_agent_server.py<br/>FastMCP — workflow-level tools"]
    B["zephyr_mcp_server.py<br/>FastMCP — atomic tool definitions, logging"]
    C["zephyr_client.py<br/>Jira + Zephyr Scale REST client"]
    D["Your Jira Instance<br/>jira.yourcompany.net"]
    E["Azure Key Vault / .env<br/>secrets resolved at runtime"]
    L["Your LLM Endpoint<br/>Anthropic / OpenAI / Azure / gateway"]

    A -->|stdio / streamable-http| B
    A -->|stdio / streamable-http| G
    G -->|run_agent| F
    F -->|in-process tool calls| B
    F <-->|tool-call loop| L
    B --> C
    C -->|REST API + JIRA_TOKEN| D
    E -->|Runtime secrets| C
    E -->|Runtime secrets| L

    style A fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
    style F fill:#fdf3e3,stroke:#e8710a,stroke-width:2px
    style G fill:#fdf3e3,stroke:#e8710a,stroke-width:2px
    style B fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
    style C fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
    style D fill:#e6f4ea,stroke:#188038,stroke-width:2px
    style E fill:#fff4e5,stroke:#f29900,stroke-width:2px
    style L fill:#f3e8fd,stroke:#9334e6,stroke-width:2px

Prerequisites

  • Python 3.10+

  • Access to a Jira instance with Zephyr Scale (ATM) enabled

  • An Azure Key Vault instance holding your Jira API token as a secret named JIRA-TOKEN, with the identity running this server granted get/list access to that secret

  • An MCP-compatible client (e.g. Claude Desktop)

  • (Agent layer only) an LLM endpoint — Anthropic/OpenAI/Azure OpenAI or an internal gateway — with its API key in Key Vault (e.g. ANTHROPIC-API-KEY); see AGENT_LAYER.md

Setup

  1. Clone and install dependencies

    git clone https://github.com/VenkateshDoijode/custom-mcp.git
    cd custom-mcp
    pip install -r requirements.txt
  2. Configure config.toml with your Jira details (and LLM settings if you want the agent layer)

    [jira]
    base_url = "https://jira.yourcompany.net"
    username = "your-jira-username"
    
    [azure]
    key_vault_url = "https://your-keyvault-name.vault.azure.net/"
    
    [llm]                       # agent layer only — see AGENT_LAYER.md §3–4
    provider = "anthropic"      # or openai | azure_openai | openai_compatible
    model = "claude-sonnet-4-5"
  3. Provide secrets — either grant Key Vault access to the identity running the server (managed identity, service principal, or az login), scoped to read JIRA-TOKEN only; or copy .env.example to .env and fill in values (never commit .env). Environment variables always take precedence.

  4. Register the server(s) with your MCP client — see claude_desktop_config.json for a working example, and point it at the absolute path of zephyr_mcp_server.py (atomic tools) and/or zephyr_agent_server.py (workflow agent).

  5. Run it

    python zephyr_mcp_server.py          # atomic tools — stdio for MCP clients
    python zephyr_mcp_server.py --http   # streamable-http on port 8000
    python zephyr_agent_server.py        # agent layer — stdio for MCP clients
    python zephyr_agent.py "instruction" # agent CLI — no MCP client needed

Use with Any Coding Agent

Each server works completely independently. Register one, the other, or both — they are separate FastMCP servers with no shared runtime state:

Server

Exposes

Use it for

zephyr_mcp_server.py

~20 atomic Jira/Zephyr tools

Fine-grained control — "create one test case", "comment on PG1-123"

zephyr_agent_server.py

5 workflow-level tools (run_workflow, cover_story, audit_sprint, release_report, list_workflows)

Multi-step jobs — "cover this story end-to-end", "audit the sprint"

Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, Devin, VS Code MCP, or a custom agent — registers them the same way, as stdio processes:

{
  "mcpServers": {
    "zephyr-tools": {
      "command": "python",
      "args": ["/absolute/path/to/custom-mcp/zephyr_mcp_server.py"]
    },
    "zephyr-agent": {
      "command": "python",
      "args": ["/absolute/path/to/custom-mcp/zephyr_agent_server.py"]
    }
  }
}
  • Claude Desktop → claude_desktop_config.json (working example in this repo)

  • Cursor / Windsurf → ~/.cursor/mcp.json / ~/.codeium/windsurf/mcp_config.json — same mcpServers shape

  • HTTP clients → start either server with --http and point the client at http://localhost:8000/mcp

  • No MCP client at all → python zephyr_agent.py "instruction" runs the agent layer directly from the shell

Each server validates config and credentials at startup — a bad setup exits with a clear error in the client's log instead of failing mid-conversation.

Security Posture

Concern

How it's handled here

Credential storage

Jira token pulled from Azure Key Vault at runtime, or from env vars / a gitignored .env file; never stored in code, config, or logs

Startup validation

validate_config() runs at server/CLI boot — missing URL, non-HTTPS Jira, or missing/placeholder token fails immediately

Network exposure

Server runs locally/on-prem; only outbound calls are to your own Jira base URL

Data residency

No third-party proxy or SaaS relay — test and issue data never leaves your network boundary

Least privilege

Tools are scoped to specific Jira/Zephyr operations, not a general-purpose API proxy

Auditability

All tool invocations are logged with the acting user, action, and target key

Destructive actions

Operations like delete_test_case are explicit, named tools — never a hidden side effect of another call

This is a personal/team project, not an officially reviewed enterprise product. Before deploying it in a regulated environment, run it through your organization's standard security and architecture review — the design choices above are meant to make that review straightforward, not to replace it.

AI Agent Layer

The atomic tools above are now wrapped by an agent layer: hand over a whole workflow in one instruction — "Generate test cases for this new story, link them, and audit last sprint's execution cycle for gaps." — and the agent chains resolution → creation → linking → reporting itself.

  • Independent second MCP server (zephyr_agent_server.py) — register it in any MCP-compatible coding agent alongside or instead of the atomic server.

  • Provider-agnostic — Anthropic, OpenAI, Azure OpenAI, or any OpenAI-compatible gateway (LiteLLM, vLLM, Ollama, internal). One [llm] block in config.toml selects provider/model/endpoint/auth; keys resolve from Azure Key Vault like the Jira token.

  • CLI (zephyr_agent.py) — free-form instructions plus predefined workflows (cover_story, audit_sprint, release_report), with --dry-run, approval prompts, and a destructive-tool gate.

  • Same audit trail — the agent orchestrates the atomic tools in-process, so every action is still logged in zephyr_mcp.log.

python zephyr_agent.py --workflow cover_story --arg issue_key=PG1-123
python zephyr_agent_server.py            # stdio — register in your MCP client

Full setup, provider configs, and guardrails: AGENT_LAYER.md — complete run/start runbook: RUN_AGENT.md.

Agent mode sends Jira issue/story content to the configured LLM endpoint — choose azure_openai or an internal openai_compatible gateway to keep that traffic inside your network boundary, and review it under the same security process as the rest of this project.

Repository Contents

File

Purpose

zephyr_mcp_server.py

FastMCP server — registers all atomic tools, handles logging and transport

zephyr_client.py

Jira + Zephyr Scale REST client — the only module that makes Jira HTTP calls

zephyr_agent_server.py

Independent MCP server exposing the AI agent layer (workflow-level tools)

zephyr_agent.py

Agent engine (run_agent), predefined workflows, CLI (--chat for multi-turn)

zephyr_agent_ui.py

OPTIONAL FastAPI browser chat UI over the same engine (pip install fastapi uvicorn)

llm_providers.py

Provider-agnostic LLM adapters (Anthropic / OpenAI / Azure OpenAI / gateways)

docs/AGENT_LAYER.md

End-to-end agent layer documentation

docs/RUN_AGENT.md

Detailed runbook — how to run/start the agent (CLI, MCP, API, cron)

docs/MCP_EXPLAINED.md

What MCP and FastMCP are, and how this project layers them

docs/DRY_RUN_EXAMPLE.md

Captured real dry-run — guardrails and tabular output in action

.env.example

Documented env-var / .env template for secrets and LLM config

claude_desktop_config.json

Example MCP client configuration

requirements.txt

Python dependencies (tail has optional UI deps, safe to skip)

Author

Venkateshwara Doijode — Test Automation Lead

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers