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):

{
  "mcpServers": {    
    "abstract": {
      "command": "abstract-mcp",
      "args": [
        "/path/to/allowed/storage/dir1",
        "/path/to/allowed/storage/dir2"
      ],
      "env": {
        "APP_CONFIG_PATH": "/path/to/claude/desktop/config.json",
        "ABSTRACT_PROXY_SERVERS": "server1,server2"
      }
    }
  }
}

Example with Existing MCP Servers

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

{
  "mcpServers": {    
    "abstract": {
      "command": "abstract-mcp",
      "args": [
        "/path/to/allowed/storage/dir1",
        "/path/to/allowed/storage/dir2"
      ],
      "env": {
        "APP_CONFIG_PATH": "/path/to/claude/desktop/config.json",
        "ABSTRACT_PROXY_SERVERS": "tavily-mcp"
      }
    },
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-tavily-api-key"
      }
    }
  }
}

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

Tool	Purpose	When to Use
call_tool_and_store	Cache large responses to files	Web searches, database queries, file operations
call_tool	Direct tool calls in context	Small responses, status checks, quick calculations
call_tool_with_file_content	Upload file data to tools	Bulk imports, config deployments, data processing
list_available_tools	Discover upstream tools	Before calling any upstream tools
list_tool_details	Get tool parameter schemas	When you need exact parameter requirements
list_allowed_directories	View storage locations	Before using custom storage paths

Usage Examples

Basic Response Caching

{
  "server": "tavily-mcp",
  "tool_name": "search", 
  "tool_args": {"query": "bitcoin ETF flows", "max_results": 10}
}

Advanced: Custom Storage & Format

{
  "server": "tavily-mcp",
  "tool_name": "search",
  "tool_args": {"query": "bitcoin ETF flows", "max_results": 10},
  "storage_path": "/Users/you/Documents/research",
  "filename": "bitcoin-etf-analysis",
  "file_format": "csv"
}

File Upload to Tools

{
  "server": "database-mcp",
  "tool_name": "bulk_insert",
  "file_path": "/Users/you/Documents/users.csv",
  "data_key": "records",
  "tool_args": {"table": "users"}
}

File Format Support

Format	Use Case	Example Output
json	Structured data (default)	Clean JSON without MCP metadata
csv	Spreadsheet analysis	Headers + data rows
md	Documentation	Formatted markdown
yaml	Configuration files	Key-value structured data
txt	Plain text	Universal format
html	Web content	Formatted HTML
xml	API responses	Structured markup
tsv	Tab-separated data	Excel-compatible format

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

# Logs are written to stderr - capture with your log aggregator
abstract-mcp 2>> /var/log/abstract-mcp.log

# Key log patterns to monitor:
# "Loaded N upstream server configurations" - startup success
# "Failed to call upstream tool" - tool call failures
# "Storage directories:" - directory configuration

Error Handling

Error Type	Behavior	Recovery
Upstream server unreachable	Returns error message, continues serving	Check server config and dependencies
Storage directory not writable	Fails with clear error message	Verify directory permissions
File size exceeded	Rejects upload with size limit error	Use smaller files or increase limit
Invalid JSON in config	Logs error, continues with empty config	Fix JSON syntax in config file

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

# Test configuration
abstract-mcp /tmp/test-dir
# Should show: "Storage directories: /tmp/test-dir"

# Verify upstream server connectivity
export APP_CONFIG_PATH="/path/to/config.json"
export ABSTRACT_PROXY_SERVERS="tavily-mcp"
# Look for: "Loaded 1 upstream server configurations"

# Check directory permissions
ls -la /your/storage/directory
# Should be writable by the user running abstract-mcp

Development

Command	Purpose
npm run build	Compile TypeScript to dist/
npm run dev	Build and start development server
npm start	Start compiled production server
npm test	Run test suite
npm run test:watch	Continuous testing during development

Architecture

MCP Client (Claude/Cursor/etc) ──(stdio JSON-RPC)──► Abstract (Node.js)
                                                          │
                                                          ├── Reads client config file
                                                          ├── Validates storage directories
                                                          │
                                                          ▼
                                              Upstream MCP servers (stdio)
                                                          │
                                                          ▼
                                           User-specified directories/<uuid>.json

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