From mcp-exec
Use when discovering available MCP tools or when any MCP tool call would return large results you want to keep out of the context window — including single-tool calls
How this skill is triggered — by the user, by Claude, or both
Slash command
/mcp-exec:using-mcp-execThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Core principle: Keep large MCP results out of context — filter and return only what you need.
Core principle: Keep large MCP results out of context — filter and return only what you need.
Call the tool directly when:
PreToolUse/PostToolUse hook to fire for that specific callUse exec() when:
The single-tool case matters: one MCP call returning 200 records costs 8,000 tokens if it hits context; exec() can reduce it to a 50-token summary.
// List all available tools
tools("*")
// Search for specific tools
tools("search emails")
tools("github pull request")
tools("drive create document")
Returns trimmed summaries: { server, name, description, signature }. Full schemas never enter context.
import { searchEmails, sendEmail } from 'mcp/gmail';
import { searchFiles, createDocument } from 'mcp/gdrive';
Server names match keys in .claude/mcp.json. Imports are resolved at runtime.
// Node.js (default): return value becomes the result
exec({
runtime: "node",
code: `
import { searchEmails } from 'mcp/gmail';
const emails = await searchEmails({ query: 'from:boss subject:urgent' });
return emails.length + ' urgent emails';
`
})
// Bash: stdout becomes the result
exec({
runtime: "bash",
code: "echo 'hello world' | tr '[:lower:]' '[:upper:]'"
})
// Python (stateless, uv-isolated): stdout is the result. No MCP imports — data processing only.
exec({
runtime: "python",
code: `
# /// script
# dependencies = ["pandas"]
# ///
import pandas as pd, json
with open('/tmp/mcp-exec-data.json') as f:
rows = json.load(f)
df = pd.DataFrame(rows)
print(df.groupby('category')['value'].mean().round(2).to_json())
`
})
Variables on globalThis persist across exec() calls in the same conversation. Bash and Python are stateless — thread data explicitly.
// Call 1 — fetch and store
exec({ runtime: "node", code: `
import { searchEmails } from 'mcp/gmail';
globalThis.emails = await searchEmails({ query: 'is:unread' });
return globalThis.emails.length + ' emails fetched';
`});
// Call 2 — same session, state persists
exec({ runtime: "node", code: `
const urgent = globalThis.emails.filter(e => e.subject.includes('URGENT'));
return urgent.map(e => e.subject);
`});
Bash cannot access Node session globals. Thread data via temp files for large payloads.
// Step 1 (node): fetch and write to temp file
const nodeResult = await exec({ runtime: "node", code: `
import { searchFiles } from 'mcp/gdrive';
import { writeFileSync } from 'fs';
const files = await searchFiles({ query: 'Q4 report' });
writeFileSync('/tmp/mcp-exec-result.json', JSON.stringify(files));
return files.length + ' files written';
`});
// Step 2 (bash): read from temp file — never interpolate JSON into shell strings
const filtered = await exec({
runtime: "bash",
code: `jq '[.[] | select(.mimeType == "application/pdf") | .name]' /tmp/mcp-exec-result.json`
});
Errors return as { error, line, column }. Line numbers are relative to your code.
const result = await exec({ runtime: "node", code: `...` });
if (typeof result.result === 'object' && 'error' in result.result) {
// Retry with fixed code
}
| Thought | Reality |
|---|---|
| "It's just one tool call, not worth the overhead." | If the response is large, exec() saves context even for a single call. |
| "I'll call the tool directly and filter afterwards." | Tokens spent on large responses can't be unspent. Filter inside exec(). |
| "The result is probably small." | Check the tool signature with tools(query) first, then decide. |
| "I need to see the raw output." | Only true if you need to reason over it. If you just need a subset, filter in exec(). |
PreToolUse/PostToolUse hook must fire for that specific callFull API, session state, bundled packages, and cross-runtime patterns:
ts-sdk-reference.md — Node.js runtimepy-sdk-reference.md — Python runtimeSearches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Implements vector databases with Pinecone, Weaviate, Qdrant, Milvus, pgvector for semantic search, RAG, recommendations, and similarity systems. Optimizes embeddings, indexing, and hybrid search.
npx claudepluginhub joeblackwaslike/agent-marketplace --plugin mcp-exec