freeplay

Freeplay Plugin for Claude Code

Give Claude Code the ability to interact with Freeplay, the ops platform for AI engineering teams.

Analyze production logs, diagnose quality issues, iterate on prompts and agents using real data, and run experiments to validate changes — all through natural language conversation.

⚠️ EXPERIMENTAL

This plugin is an experimental release and will change. Use at your own risk.

Current limitations:

• Does not support destructive deletion actions
• Does not support deployment operations
• Uses your regular Freeplay API key (not specially scoped to limit access for agents)

Security warning: Because this uses your full API key, a malicious or compromised agent could extract the key and write its own code outside the plugin to perform destructive actions against your Freeplay account.

Additionally, all MCP servers share a security context within the host, enabling data exfiltration, prompt injection across tools, and cross-server data access.

Only use this with agents and MCP servers you fully trust.

---

Installation

From the Plugin Marketplace

claude plugin marketplace add freeplayai/freeplay-plugin
claude plugin install freeplay

Set your environment variables:

export FREEPLAY_API_KEY="your-api-key"
export FREEPLAY_BASE_URL="https://app.freeplay.ai"  # optional, this is the default

Running Locally

Prerequisites

• Claude Code v1.0.33 or later (claude --version)
• uv installed
• Freeplay API key

Clone with submodules

git clone --recurse-submodules https://github.com/freeplayai/freeplay-plugin.git
cd freeplay-plugin

Or if already cloned:

git submodule update --init --recursive

Install MCP server dependencies

cd freeplay-mcp
uv sync
cd ..

Configure environment

export FREEPLAY_API_KEY="your-api-key"
export FREEPLAY_BASE_URL="https://app.freeplay.ai"  # optional, this is the default

Run the plugin

claude --plugin-dir ./

Run with debug output:

claude --debug --plugin-dir ./

Verify MCP connection

Once Claude starts, run /mcp to check the Freeplay server is connected.

Updating submodules

Pull latest changes including all submodules:

git pull --recurse-submodules

Or set this as the default behavior:

git config submodule.recurse true

After updating, reinstall dependencies:

cd freeplay-mcp && uv sync && cd ..

MCP Server

This plugin bundles the Freeplay MCP server. See the MCP server README for standalone installation, available tools, and configuration options.

Developing with a local MCP server

By default, .mcp.json runs the published MCP server via uvx freeplay-mcp. To test against a local copy of the MCP server (e.g. the freeplay-mcp submodule), replace the .mcp.json config:

{
  "mcpServers": {
    "freeplay": {
      "command": "uv",
      "args": ["--directory", "./freeplay-mcp", "run", "freeplay-mcp"],
      "env": {}
    }
  }
}

Make sure to initialize the submodule and install dependencies first:

git submodule update --init --recursive
cd freeplay-mcp && uv sync && cd ..

Troubleshooting

Plugin not loading:

• Verify directory structure (components at root, not inside .claude-plugin/)
• Run with --debug flag to see loading errors

MCP server not connecting:

• Ensure submodule is initialized: git submodule update --init
• Run uv sync in the freeplay-mcp/ directory
• Check FREEPLAY_API_KEY is set

Support

• Docs: https://docs.freeplay.ai
• Issues: https://github.com/freeplayai/freeplay-plugin/issues
• Security: security@freeplay.ai