MCP Client

MCP Client

Use the mcp_client tool to connect to external MCP servers and interact with their tools and resources using the Model Context Protocol (Streamable HTTP transport).

Tool: mcp_client

Workflow

Every interaction follows the same pattern:

1. Initialize — connect to the server (may return a session ID)
2. Use — list tools, call tools, list resources, read resources
3. Close — end the session when done

If initialize returns a session_id, pass it to all subsequent calls. Some servers are stateless and return an empty session ID — in that case, omit it.

Actions

Parameters

Examples

Connect to a local MCP server

mcp_client(action="initialize", url="http://localhost:8080/mcp")

Returns:

{
  "session_id": "abc-123-def",
  "protocol_version": "2025-03-26",
  "server_info": {"name": "IonClaw", "version": "1.0.0"},
  "capabilities": {"tools": {"listChanged": false}}
}

Connect with authentication

mcp_client(action="initialize", url="http://localhost:8080/mcp", auth_token="your-bearer-token")

List available tools

mcp_client(action="list_tools", url="http://localhost:8080/mcp", session_id="abc-123-def")

Call a remote tool

mcp_client(action="call_tool", url="http://localhost:8080/mcp", session_id="abc-123-def", tool_name="chat", tool_arguments={"message": "Hello, what can you do?"})

List resources

mcp_client(action="list_resources", url="http://localhost:8080/mcp", session_id="abc-123-def")

Read a resource

mcp_client(action="read_resource", url="http://localhost:8080/mcp", session_id="abc-123-def", resource_uri="ionclaw://agents")

Ping the server

mcp_client(action="ping", url="http://localhost:8080/mcp", session_id="abc-123-def")

Close the session

mcp_client(action="close", url="http://localhost:8080/mcp", session_id="abc-123-def")

Complete workflow example

A typical session looks like this:

# 1. connect
mcp_client(action="initialize", url="http://localhost:9090/mcp")
# → session_id: "abc-123"

# 2. discover what the server offers
mcp_client(action="list_tools", url="http://localhost:9090/mcp", session_id="abc-123")
# → tools: [{name: "query_db", ...}, {name: "insert_record", ...}]

# 3. use a tool
mcp_client(action="call_tool", url="http://localhost:9090/mcp", session_id="abc-123", tool_name="query_db", tool_arguments={"sql": "SELECT * FROM users LIMIT 5"})
# → {tool: "query_db", text: "...", isError: false}

# 4. read a resource
mcp_client(action="read_resource", url="http://localhost:9090/mcp", session_id="abc-123", resource_uri="myapp://schema/users")
# → {uri: "myapp://schema/users", text: "..."}

# 5. close when done
mcp_client(action="close", url="http://localhost:9090/mcp", session_id="abc-123")
# → {status: "closed"}

Tips

• Always call initialize first to negotiate the protocol version and capabilities.
• If the server returns a session_id, pass it to all subsequent calls. If it returns empty, omit it.
• Use list_tools to discover what the remote server can do before calling tools.
• The session_id is specific to one server — if you connect to multiple servers, track each session ID separately.
• Use auth_token when the server requires authentication (Bearer token).
• For long-running tool calls, increase the timeout parameter.
• Always close the session when you are done to free server resources.
• The tool uses the MCP Streamable HTTP transport (JSON-RPC 2.0 over HTTP POST).