JE
OfficialSecurity

Jellyfish MCP Server Security Advisory

Review security guidance before deploying this Jellyfish MCP server; consult SECURITY.md for known risks and implementation limitations.

View on GitHub
Quick Install
npx -y @Jellyfish-AI/jellyfish-mcp

Overview

This MCP (Model Context Protocol) server exposes Jellyfish API data to host applications (for example Claude Desktop, Cursor, or VSCode) so language models can answer natural-language queries about engineering metrics, teams, allocations, delivery, and more. The server maps specific Jellyfish API endpoints into MCP “tools” the host can call; hosts can use these tools to retrieve structured data that a model can reason over when answering user prompts.

Before deploying, review SECURITY.md in the repository for documented risks and implementation limitations. This implementation includes optional integration with a PromptGuard verifier (Meta Llama PromptGuard via Hugging Face) to reduce prompt-injection risk, but it is not a complete mitigation. Treat API tokens and model safeguards as part of a defense-in-depth approach.

Features

  • Bridges Jellyfish API data into MCP-compatible tools for LLM hosts
  • Tool-per-endpoint design: each Jellyfish endpoint is exposed as an MCP tool
  • Optional PromptGuard verification to reduce prompt injection risk
  • Multiple deployment paths: Claude Desktop extension, Docker container, or local Node run
  • Lightweight required configuration: Jellyfish API token is mandatory; PromptGuard-related variables are optional

Installation / Configuration

Prerequisites

  • Jellyfish API token (required)
  • Optional: Hugging Face token with access to PromptGuard models (for PromptGuard integration)
  • For Docker: Docker installed
  • For local: Node.js (v18+ recommended) and npm

Environment variables

JELLYFISH_API_TOKEN       # required — Jellyfish API token
HUGGINGFACE_API_TOKEN     # optional — enables PromptGuard verification
MODEL_AVAILABILITY=false  # optional — allow data when PromptGuard is unreachable? (true|false). Default: false
MODEL_TIMEOUT=10          # optional — seconds to wait for PromptGuard. Default: 10

Example .claude.json / mcp.json (snippet)

{
  "transport": "stdio",
  "env": {
    "JELLYFISH_API_TOKEN": "xxx-your-jellyfish-token-xxx",
    "HUGGINGFACE_API_TOKEN": "hf_xxx-your-hf-token-xxx",
    "MODEL_AVAILABILITY": "false",
    "MODEL_TIMEOUT": "10"
  }
}

Docker (recommended for hosts that support stdio transport)

# Example: register with Claude's MCP using stdio transport
claude mcp add --transport stdio jellyfish-mcp -- \
  docker run -i --rm --pull always \
  -e JELLYFISH_API_TOKEN -e HUGGINGFACE_API_TOKEN \
  jellyfishco/jellyfish-mcp:latest

Local (development / modification)

git clone https://github.com/Jellyfish-AI/jellyfish-mcp.git
cd jellyfish-mcp
npm install
# Start with env vars set
export JELLYFISH_API_TOKEN="xxx"
export HUGGINGFACE_API_TOKEN="hf_xxx"   # optional
npm start

Claude Desktop extension

  • Download the .mcpb file from the repository releases and install via Claude Desktop. Follow the extension prompts to supply required tokens.

Available Tools / Resources

The server exposes tools grouped by Jellyfish domain. Each tool maps to a Jellyfish API endpoint.

General

  • get_api_schema

Allocations

  • allocations_by_person
  • allocations_by_team
  • allocations_by_investment_category
  • allocations_by_investment_category_person
  • allocations_by_investment_category_team
  • allocations_by_work_category
  • allocations_by_work_category_person
  • allocations_by_work_category_team
  • allocations_filter_fields
  • allocations_summary_by_investment_category
  • allocations_summary_by_work_category

Delivery

  • deliverable_details
  • deliverable_scope_and_effort_history
  • work_categories
  • work_category_contents

DevEx

  • devex_insights_by_team

Metrics

  • company_metrics
  • person_metrics
  • team_metrics
  • team_sprint_summary
  • unlinked_pull_requests

People & Teams

  • list_engineers
  • search_people
  • list_teams
  • search_teams

Each tool accepts parameters consistent with the corresponding Jellyfish API endpoint (filtering, date ranges, pagination). Use get_api_schema to inspect available endpoints and schemas programmatically.

Use Cases (concrete examples)

  • “What were our company metrics in December 2025?”

    • Host requests company_metrics for a date range; model synthesizes a human-readable summary using returned values.

  • “List unlinked pull requests in the last 30 days”

    • Call unlinked_pull_requests with timeframe parameters to surface PRs that lack tracking/delivery linkage.

  • “Show allocations by person for Q1 2026”

    • Use allocations_by_person with start/end dates and grouping to produce a per-person allocation breakdown.

Example flow (high level)

  1. User asks a question in the host app.
  2. Host invokes an MCP tool (e.g., team_metrics) with structured parameters.
  3. Server fetches data from Jellyfish API, optionally runs PromptGuard verification, and returns structured JSON to the host.
  4. LLM composes a human-friendly response using that data.

Security Advisory & Best Practices

Important: consult SECURITY.md in the project root for known risks and implementation limitations before using this server in production.

Key recommendations

  • Secrets: never commit JELLYFISH_API_TOKEN or HUGGINGFACE_API_TOKEN to source control. Use environment variables or a secrets manager.
  • Least privilege: limit API token permissions and token time-to-live in Jellyfish. Rotate tokens regularly.
  • Network exposure: do not bind the server to a public interface unless protected by a firewall or reverse proxy with authentication. Prefer running in a private network or via stdio transport when used by a local host.
  • Prompt injection: PromptGuard integration helps but is not foolproof. Treat returned data as privileged and combine PromptGuard with additional application-level input/output sanitization and filtering.
  • Monitoring & rate limits: monitor API usage and logs for anomalous requests. Respect Jellyfish rate limits and add retry/backoff logic.
  • Container hardening: run containers with non-root users, limit capabilities, and keep images up-to-date. Scan dependencies and update frequently.
  • Fail-open vs fail-closed: configure MODEL_AVAILABILITY according to your risk tolerance. Setting MODEL_AVAILABILITY=false blocks data when PromptGuard is unavailable; true allows data to flow.
  • Audit and review: review and test the MCP behavior in a staging environment and validate that the outputs match organizational security policies.

Where to get more information

  • Source and releases: https://github.com/Jellyfish-AI/jellyfish-mcp
  • Security guidance and known issues: see SECURITY.md in the repository
  • API schema: use the get_api_schema tool to inspect available endpoints and field types programmatically

If you plan to deploy this server in production, perform a security review tailored to your environment and combine the server’s optional protections

Tags:security