mcp-compressor
An MCP server wrapper for reducing tokens consumed by MCP tools, available in typescript, python, and rust
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/atlassian-labs/mcp-compressor with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/atlassian-labs/mcp-compressor'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/atlassian-labs--mcp-compressor)HTML
<a href="/listings/atlassian-labs--mcp-compressor"><img src="/api/listings/atlassian-labs--mcp-compressor/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 199 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # mcp-compressor
- [](https://mcptoplist.com/server/glama%2Fatlassian-labs%2Fmcp-compressor)
- [](https://github.com/atlassian-labs/mcp-compressor/releases)
- [](https://github.com/atlassian-labs/mcp-compressor/actions/workflows/main.yml?query=branch%3Amain)
- [](https://github.com/atlassian-labs/mcp-compressor/commits/main)
- [](https://github.com/atlassian-labs/mcp-compressor/blob/main/LICENSE)
- `mcp-compressor` helps agents use large MCP servers without spending huge amounts of context on tool descriptions and schemas.
- It can run as a CLI MCP proxy, or be embedded directly from Python, TypeScript, or Rust.
- - **Documentation**: <https://atlassian-labs.github.io/mcp-compressor/>
- - **Repository**: <https://github.com/atlassian-labs/mcp-compressor/>
- - **Blog**: <https://www.atlassian.com/blog/developer/mcp-compression-preventing-tool-bloat-in-ai-agents/>
- ## Why mcp-compressor?
- A powerful MCP server can expose dozens or hundreds of tools. Each tool has a name, description, input schema, and sometimes large nested JSON Schema details. Sending all of that to a model up front can waste thousands of tokens before the agent has done any useful work.
- For example, large public MCP servers can spend thousands or tens of thousands of tokens on tool descriptions alone. That creates three problems:
- - models spend context on tools they may never call,
- - cost increases for every request that carries the tool list,
- - adding multiple MCP servers quickly overwhelms practical context budgets.
- `mcp-compressor` changes the interaction pattern: the model sees a small compressed surface first, asks for the full schema only for the selected tool, and then invokes that tool.
- Opt into bounded tool responses in any proxy mode with `--shrinkfit` (20,000
- characters) or `--shrinkfit=10000`. Object responses retain their top-level shape
- and add `truncation` instructions. CLI/Code/Just Bash sessions save the full
- original in a private temporary file; MCP callers can recall with `full=true`
- using a session cache or bypassing shrinking on a backend call. See
- [recoverable response shrinking](https://atlassian-labs.github.io/mcp-compressor/usage/shrinkfit/).
- ## Pattern 1: compressed MCP proxy
- Use this when you want any MCP client to see a smaller tool surface.
- ```mermaid
- sequenceDiagram
- participant Client as MCP client / agent
- participant Proxy as mcp-compressor
- participant Backend as Backend MCP server
- Client->>Proxy: tools/list
- Proxy->>Backend: tools/list
- Backend-->>Proxy: all backend tools and schemas
- Proxy-->>Client: compact wrapper tools
- Client->>Proxy: get_tool_schema(tool_name)
- Proxy-->>Client: full schema for selected tool
- Client->>Proxy: invoke_tool(tool_name, input)
- Proxy->>Backend: tools/call selected backend tool
- Backend-->>Proxy: tool result
- Proxy-->>Client: result
- ```
- The frontend usually exposes only:
- - `get_tool_schema`
- - `invoke_tool`
- - optionally `list_tools` at `max` compression
- ### MCP protocol negotiation
- The stdio and streamable HTTP frontends accept both legacy `initialize` clients
- and modern `2026-07-28` discovery clients, including Python MCP SDK 2.2.0 in
- `auto`, `legacy`, or explicit `2026-07-28` mode. Backend connections initialize
- independently, so modern clients can use legacy backends without sending
- frontend negotiation metadata to them. Backends must support legacy `initialize`;
- modern-only backends are not supported. Application tool-call metadata and tool
- result content, annotations, structured content, and error flags are preserved.
- Modern catalog and resource-read responses use `ttlMs: 0` and private cache
- scope. Catalogs remain static for the connection; dynamic change subscriptions
- are not advertised or supported. Legacy responses omit modern protocol fields.
- ## Pattern 2: local proxy for SDKs and generated clients
- Use this when your application wants to embed compression directly and call tools from code or shell commands.
- ```mermaid
- flowchart LR
- App[Python / TypeScript / Rust app]
- SDK[CompressorClient]
- Proxy[Local session proxy\n/token auth]
- Generated[Generated CLI / Python / TS clients]
- Backend[MCP backend servers]
- App --> SDK
- SDK --> Proxy
- Generated --> Proxy
- Proxy --> Backend
- ```
- The SDK starts a local session proxy for generated clients. Generated clients call that proxy using a session token. Your app does **not** need to spawn a `mcp-compressor` stdio subprocess.
- ## Features
- - [Compressed MCP proxy](https://atlassian-labs.github.io/mcp-compressor/usage/cli/#standard-mcp-proxy) for existing MCP clients.
- - [Compression levels](https://atlassian-labs.github.io/mcp-compressor/concepts/how-it-works/#compression-levels): `low`, `medium`, `high`, `max`.
- - [Python, TypeScript, and Rust SDKs](https://atlassian-labs.github.io/mcp-compressor/usage/sdks/) with aligned `CompressorClient` APIs.
- - [Local TypeScript tool compression](https://atlassian-labs.github.io/mcp-compressor/usage/sdks/#compress-local-typescript-tools) for AI SDK-style in-process tools.
- - [CLI Mode and Code Mode generated clients](https://atlassian-labs.github.io/mcp-compressor/usage/generated-clients/): shell commands plus Python/TypeScript functions.
- - [Just Bash integration](https://atlassian-labs.github.io/mcp-compressor/usage/just-bash/) for command-oriented agents.
- - [Remote streamable HTTP MCP backends](https://atlassian-labs.github.io/mcp-compressor/usage/auth-and-remote/).
- - [OAuth support](https://atlassian-labs.github.io/mcp-compressor/usage/auth-and-remote/#native-oauth) for providers that support browser authorization.
- - [Tool filters and TOON output](https://atlassian-labs.github.io/mcp-compressor/concepts/configuration/#filters) to further reduce context.
- - [Atlassian MCP example](https://atlassian-labs.github.io/mcp-compressor/examples/atlassian/) with OAuth-first usage.
- ## Quick example
- === "CLI"
- ```bash
- mcp-compressor -c medium -- python server.py
- ```
- === "Python"
- ```python
- from mcp_compressor import CompressorClient
- with CompressorClient(
- servers={"alpha": {"command": "python", "args": ["server.py"]}},
- compression_level="medium",
- ) as proxy:
- print([tool.name for tool in proxy.tools])
- print(proxy.invoke("echo", {"message": "hello"}))
- ```
- === "TypeScript"
- ```ts
- import { CompressorClient } from "@atlassian/mcp-compressor";
- const proxy = await new CompressorClient({
- servers: { alpha: { command: "python", args: ["server.py"] } },
- compressionLevel: "medium",
- }).connect();
- try {
- console.log(proxy.tools.map((tool) => tool.name));
- console.log(await proxy.invoke("echo", { message: "hello" }));
- } finally {
- proxy.close();
- }
- ```
- === "Rust"
- ```rust
- use mcp_compressor::compression::CompressionLevel;
- use mcp_compressor::sdk::{CompressorClient, ServerConfig};
- use serde_json::json;
- let proxy = CompressorClient::builder()
- .server("alpha", ServerConfig::command("python").arg("server.py"))
- .compression_level(CompressionLevel::Medium)
- .build()
- .connect()
- .await?;
- let result = proxy.invoke("echo", json!({ "message": "hello" })).await?;
- ```
- ## Generated clients
- **CLI Mode** generates shell commands:
- ```bash
- mcp-compressor --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp
- atlassian get-accessible-atlassian-resources
- ```
- **Code Mode** generates Python or TypeScript functions:
- ```python
- # generated-py/atlassian.py
- import atlassian
- resources = atlassian.get_accessible_atlassian_resources()
- ```
- ```ts
- import { getAccessibleAtlassianResources } from "./generated-ts/atlassian.ts";
- const resources = await getAccessibleAtlassianResources();
- ```
- See [Code Mode and generated clients](https://atlassian-labs.github.io/mcp-compressor/usage/generated-clients/) for more detail.
- ## Where to go next
- 1. [Install the package you need](https://atlassian-labs.github.io/mcp-compressor/getting-started/installation/).
- 2. Run the [quickstart](https://atlassian-labs.github.io/mcp-compressor/getting-started/quickstart/).
- 3. Read [how compression works](https://atlassian-labs.github.io/mcp-compressor/concepts/how-it-works/).
- 4. Choose between [CLI usage](https://atlassian-labs.github.io/mcp-compressor/usage/cli/), [SDK usage](https://atlassian-labs.github.io/mcp-compressor/usage/sdks/), [generated clients](https://atlassian-labs.github.io/mcp-compressor/usage/generated-clients/), and [Just Bash](https://atlassian-labs.github.io/mcp-compressor/usage/just-bash/).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.