Abstract MCP Server

Prevents large MCP tool responses from consuming your LLM's context window. Abstract acts as a smart proxy that caches responses to files and returns compact resource links, and supports direct tool calls and file uploads to avoid context bloat.

Why Abstract?

• 🚀 Preserves Context Window: Large responses (search results, file contents, API data) don't bloat your conversation

• 💾 Smart Storage: Responses saved to directories you control with security validation

• 🔄 Format Conversion: Automatic conversion to CSV, YAML, JSON, Markdown, and more

• 📂 File Uploads: Inject CSV, JSON, YAML, and other file data into upstream tools without exposing raw content

• ⚡ Direct Calls: Skip caching when responses are small with plain call_tool for instant results

• 🔗 Zero Config: Works with your existing MCP servers without changes

Quick Start

1. Install: npm install -g abstract-mcp (or build from source)

2. Add to your MCP client config (Claude Desktop, Cursor, Cline, etc):

Example with Existing MCP Servers

Your existing MCP servers work unchanged alongside Abstract. Here's an example configuration:

Config Path Examples

Set APP_CONFIG_PATH to your MCP client's config file:

• Claude Desktop (macOS): /Users/username/Library/Application Support/Claude/claude_desktop_config.json

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json

• Cursor: ~/.cursor/config.json

• Other clients: Check your client's documentation for config location

Abstract reads this config file to find the settings for servers listed in ABSTRACT_PROXY_SERVERS.

Best Practice: Disable Upstream Tools

For more reliable tool calling, consider disabling the direct tools from upstream servers that you've added to Abstract's ABSTRACT_PROXY_SERVERS. This prevents confusion and ensures all calls go through Abstract's enhanced functionality (caching, file handling, format conversion).

Why? When both Abstract and upstream servers expose the same tools, AI assistants may randomly choose between them. By disabling upstream tools, you guarantee consistent behavior through Abstract's proxy.

Core Tools

Usage Examples

Basic Response Caching

Advanced: Custom Storage & Format

File Upload to Tools

File Format Support

Usage & Performance

Performance Characteristics

• Response Time: ~100-200ms overhead per tool call

• File I/O: Asynchronous writes, no blocking operations

• Memory Usage: ~20-50MB base + upstream server requirements

• Concurrency: Handles multiple simultaneous tool calls

• File Size Limits: 10MB per file upload (configurable)

Monitoring & Observability

Error Handling

Security Considerations

• Path Validation: All file operations restricted to allowed directories

• No Code Execution: Only data processing, no arbitrary command execution

• Environment Isolation: Upstream servers inherit environment safely

• Permission Model: Requires explicit directory allowlisting

Scaling & Deployment

• Horizontal Scaling: Run multiple instances with different storage directories

• Load Balancing: Not required - each client connects to dedicated instance

• Resource Requirements: 1 CPU core, 512MB RAM minimum per instance

• Storage: Plan for 10GB+ per active user for response caching

Troubleshooting

Development

Architecture

How it works:

1. Abstract parses allowed storage directories from command line arguments

2. Reads your MCP client's config file (specified via APP_CONFIG_PATH)

3. Extracts configurations for servers listed in ABSTRACT_PROXY_SERVERS

4. When tools are called, Abstract validates storage paths and spawns upstream servers

5. Tool responses are cached to user-specified directories with security validation

6. Resource links are returned to the client, keeping large datasets out of conversation context

Key features:

• User-controlled storage: Store responses in directories you specify

• Security-first: Path validation prevents directory traversal attacks

• Client-agnostic: Works with Claude Desktop, Cursor, Cline, Windsurf, or any MCP client

• Zero duplication: Reuses existing server configurations from your client's config

• Transparent: API keys and environment variables are properly forwarded

• Flexible: Supports any MCP server that can be spawned via stdio

• Backward compatible: Existing setups continue to work without changes

Supported Upstream Servers

• Any MCP server that can be spawned via stdio

• Examples: tavily-mcp, filesystem, custom MCP servers

• Environment variables and API keys are properly forwarded

Tool Details

call_tool_and_store

Purpose: Calls upstream MCP tools and caches responses to prevent context bloat. Returns compact resource links instead of large payloads.

Parameters:

• server (required): Upstream MCP server name

• tool_name (required): Tool to call on the server

• tool_args (optional): Arguments object for the tool

• description (optional): Human-readable description for the response

• storage_path (optional): Custom directory within allowed paths

• filename (optional): Custom filename without extension

• file_format (optional): Output format (json|csv|md|txt|html|yaml|xml|tsv)

call_tool

Purpose: Calls upstream MCP tools directly and returns raw responses in conversation context. No caching or file operations.

Parameters:

• server (required): Upstream MCP server name

• tool_name (required): Tool to call on the server

• tool_args (optional): Arguments object for the tool

call_tool_with_file_content

Purpose: Reads structured data from files and passes it to upstream MCP tools to help avoid context bloat. Supports JSON and string formats.

Parameters:

• server (required): Upstream MCP server name

• tool_name (required): Tool to call on the server

• file_path (required): Path to input file within allowed directories

• data_key (optional): Parameter name for injecting file content

• tool_args (optional): Additional arguments to merge with file data

• output_format (optional): Response format (json|string)

list_available_tools

Purpose: Discovers available tools from upstream MCP servers with structured output and filtering options.

Parameters:

• detailed (optional): Include full input schemas when true (default: false)

• filter_by_server (optional): Restrict listing to specific upstream server

list_tool_details

Purpose: Gets complete definition for a specific upstream tool including input schema and parameter requirements.

Parameters:

• server (required): Upstream server name

• tool_name (required): Name of the tool to inspect

list_allowed_directories

Purpose: Lists all directories that Abstract is allowed to store responses in. No parameters required.

Parameters: None