programmatic-mcp-prototype MCP server
Commit Nov 13, 2026Enables an AI agent to dynamically discover, compose, and execute MCP tools by writing and running TypeScript code in isolated Docker containers.
Also known as domdomegg/programmatic-mcp-prototype
- Stars
- 44
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- —
What is programmatic-mcp-prototype MCP?
programmatic-mcp-prototype enables an AI agent to dynamically discover, compose, and execute MCP tools by writing and running TypeScript code in isolated Docker containers.
Summary generated from the project's README
About programmatic-mcp-prototype MCP server
Developers building autonomous agents can use this system to allow AI to dynamically discover and combine tools by writing TypeScript code. Instead of loading every available tool into the context window at once, the agent uses search_tools and execute_tool meta-tools to find what it needs. This approach reduces context usage and improves the quality of responses by only pulling in relevant capabilities when necessary.
The architecture relies on a proxy server that aggregates multiple MCP servers into a single interface. It uses a code generator to create TypeScript bindings from tool schemas and a container runner to execute that code within isolated Docker containers. Users must configure their specific MCP servers in a configuration file and provide an Anthropic API key to run the agent loop.
This setup enables complex workflows through programmatic tool composition and state persistence. By writing code, the agent can implement loops, conditionals, and error handling while storing intermediate data in a workspace directory. Users can also build a library of reusable skills by saving custom TypeScript functions that combine multiple operations into single meta-tools.
What you can do with it
- 1Discovering tools on demandAn AI agent can search for specific capabilities instead of having every tool loaded into its context immediately.
- 2Chaining multiple tool operationsA developer can task an agent with writing TypeScript code to link several different MCP tools together in a single execution.
- 3Managing long-term task dataAn agent can save files or intermediate results to a workspace directory to be used in later steps.
- 4Creating reusable automation skillsYou can instruct an agent to build a custom skill that combines multiple existing tools into one new function.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledomdomegg/programmatic-mcp-prototype is public and reachablegithub.com/domdomegg/programmatic-mcp-prototype ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-13github.com/domdomegg/programmatic-mcp-prototype ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubprogrammatic-mcp-prototype
An MCP-based agent with support for:
- progressive tool discovery
- programmatic tool composition
- state persistence
- skill building
Architecture
- Core Agent Loop: Simple while loop that can be swapped with other implementations
- MCP Proxy Server: Aggregates multiple MCP servers into one unified interface
- Code Generator: Creates TypeScript bindings from MCP tool schemas
- Container Runner: Executes TypeScript code in isolated Docker containers
Key Features
1. Progressive Tool Discovery
The model can search for and discover tools dynamically instead of loading all tools upfront. Rather than exposing hundreds of tools at once, the agent provides search_tools and execute_tool meta-tools that allow the model to find relevant tools as needed, reducing context usage and improving response quality.
2. Programmatic Tool Composition
The agent can write TypeScript code that composes MCP tools together:
// Example: The model can write code like this
import * as bash from './generated/servers/bash';
import * as computer from './generated/servers/computer';
const files = await bash.ls({ path: './documents' });
for (const file of files) {
const content = await bash.readFile({ path: file });
console.log(`File ${file}: ${content.length} bytes`);
}
3. State Persistence
Store intermediate results and data in the workspace directory:
import * as fs from 'fs/promises';
// Save CSV for later use
const csvData = await processData();
await fs.writeFile('./generated/workspace/data.csv', csvData);
// Load it in a future execution
const data = await fs.readFile('./generated/workspace/data.csv', 'utf-8');
4. Skill Building
Create reusable meta-tools that combine multiple operations:
// Build a skill in ./generated/skills/
export async function saveSheetAsCsv(sheetId: string) {
import * as sheets from '../servers/sheets';
import * as bash from '../servers/bash';
const data = await sheets.getCells({ sheetId });
const csv = data.map(row => row.join(',')).join('\n');
const path = `../workspace/sheet-${sheetId}.csv`;
await bash.writeFile({ path, content: csv });
return path;
}
// Use the skill later
import { saveSheetAsCsv } from './generated/skills/save-sheet-as-csv';
const csvPath = await saveSheetAsCsv('abc123');
Setup
- Install dependencies:
npm install
-
Configure your MCP servers in
config/servers.ts -
Set your Anthropic API key:
export ANTHROPIC_API_KEY='your-key'
- Build Docker image for code execution:
docker build -t mcp-runner:latest src/servers/container-runner
Usage
Run the agent:
npm start
How It Works
- Startup: Connects to configured MCP servers (bash, computer, container)
- Code Generation: Creates TypeScript functions for each tool with proper types
- Agent Loop: Simple while loop that calls Claude with MCP tools
- Tool Execution: Routes tool calls to appropriate backend MCP servers
- Code Execution: Runs TypeScript in isolated Docker containers
Benefits of Programmatic Tool Use
- Composition: Chain multiple tools without waiting between calls
- State: Store variables and reuse results
- Loops/Conditionals: Handle complex logic in code
- Error Handling: Try/catch and retry logic
- Efficiency: Make many tool calls in one execution
- Skills Library: Build reusable patterns over time
programmatic-mcp-prototype MCP questions
How does the agent handle tool discovery?
The agent uses progressive tool discovery, providing search and execution meta-tools so the model can find relevant tools dynamically instead of loading everything at once.
Can the agent save data between executions?
Yes, it supports state persistence by storing intermediate results and data within the workspace directory.