2.4 KiB
| name | description |
|---|---|
| mcp-forge-conventions | How to call MCP tools from within mcp-forge execute_python scripts, including tool naming and injection syntax |
mcp-forge Conventions
Tool naming
mcp-forge injects tools using their bare function name, not the namespaced name visible to the agent.
| Agent-side name | mcp-forge mcp_tools value |
In-script call |
|---|---|---|
searxng_search |
"search" |
search(...) |
searxng_fetch |
"fetch" |
fetch(...) |
rag-mcp_browse_documents |
"browse_documents" |
browse_documents(...) |
rag-mcp_search_records |
"search_records" |
search_records(...) |
The pattern: strip any server prefix (e.g. searxng_, rag-mcp_) and use only the function name.
Injection syntax
Pass a JSON array of bare tool names to mcp_tools:
mcp-forge_execute_python(
code='results = search(query="foo"); print(results)',
mcp_tools=["search", "fetch"]
)
Listing all available tools
Use the agent-side mcp-forge_list_injectable_tools tool to get the full catalogue before writing scripts:
mcp-forge_list_injectable_tools(include_schemas=false)
Returns each tool's tool_name (injected name), qualified_name (provider.tool), and provider metadata (name, transport, url). Only tools whose providers are registered in mcp-forge's own config appear here — tools available to the OpenCode agent from other MCP servers (e.g. GitHub) are NOT automatically available inside mcp-forge.
Verifying a single tool name
To confirm a specific tool name resolves before using it, pass it in mcp_tools and check the available_tools list in the response. Only successfully resolved tools appear there.
mcp-forge_execute_python(
code='print("ok")',
mcp_tools=["search"]
)
# response includes: "available_tools": ["search"]
# if the name is wrong, the whole call errors with "Tool '<name>' not found"
Return values
Injected tools return Python objects (lists, dicts). Handle both a direct value and a dict wrapper:
data = search(query="foo")
records = data.get("result", []) if isinstance(data, dict) else data
Combining searxng + mcp-forge
mcp-forge_execute_python(
code='''
results = search(query="uv python", language="en")
top = results[0]
page = fetch(url=top["url"], max_chars=2000)
print(page["content"])
''',
mcp_tools=["search", "fetch"]
)