2026-04-20 11:42:25 +02:00
---
name: mcp-forge-conventions
description: 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.
2026-04-21 19:45:44 +02:00
## Calling injected tools — keyword-only arguments
Injected tool functions are **keyword-only wrappers** . Always pass arguments by name:
```python
# correct
results = search(query="foo", language="en")
page = fetch(url="https://example.com", max_chars=2000)
# wrong — positional args raise TypeError
results = search("foo")
```
2026-04-20 11:42:25 +02:00
## Injection syntax
Pass a JSON array of bare tool names to `mcp_tools` :
```python
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.
```python
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:
```python
data = search(query="foo")
records = data.get("result", []) if isinstance(data, dict) else data
```
## Combining searxng + mcp-forge
```python
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"]
)
```
