Mcp

astro.config.mjs

@@ -53,6 +53,7 @@ export default defineConfig({
             { label: "Search", link: "/2-usage/2-5-search/" },
             { label: "x402", link: "/2-usage/2-11-x402/" },
             { label: "A2A", link: "/2-usage/2-10-a2a/" },
+            { label: "MCP", link: "/2-usage/2-12-mcp/" },
             { label: "Feedback", link: "/2-usage/2-6-use-feedback/" },
             { label: "Transfer", link: "/2-usage/2-7-transfer-agents/" },
             { label: "Client-side usage", link: "/2-usage/2-8-browser-wallets/" }
@@ -65,7 +66,8 @@ export default defineConfig({
             { label: "Agent Update", link: "/3-examples/3-2-agent-update/" },
             { label: "Feedback Usage", link: "/3-examples/3-3-feedback-usage/" },
             { label: "Search Agents", link: "/3-examples/3-4-search-agents/" },
-            { label: "x402 and A2A", link: "/3-examples/3-5-x402-a2a/" }
+            { label: "x402 and A2A", link: "/3-examples/3-5-x402-a2a/" },
+            { label: "MCP", link: "/3-examples/3-6-mcp/" }
           ]
         },
         {

src/content/docs/1-welcome/1-2-key-concepts/index.md

@@ -24,20 +24,22 @@ For MCP endpoints, capabilities are extracted from the endpoint itself:
 - **tools** - MCP tools the agent provides (e.g., “fetch_file”, “send_email”)
 - **prompts** - MCP prompts available (e.g., “summarize_text”, “analyze_code”)
 - **resources** - MCP resources accessible (e.g., “weather_data”, “stock_prices”)
+
+These are discovery/indexing signals. At runtime, call MCP using `sdk.createMCPClient(...)` (TypeScript/Python), or `agent.mcp`. For URL input, MCP uses strict direct endpoint semantics.
 ### A2A Concepts
 
-For A2A endpoints, agents define their capabilities and specific instances:
+For A2A endpoints, discovery metadata and runtime entities are distinct:
 
-- **skills** - Core abilities the agent has (e.g., “data_analysis”, “customer_support”)
-- **tasks** - Specific task names the agent can perform (e.g., “task_123_schedule_meeting”, “task_456_generate_report”)
-- **context** - Specific context names the agent can access (e.g., “ctx_user_preferences”, “ctx_company_data”)
+- **skills** - Advertised A2A capability metadata (discoverable/indexed)
+- **tasks** - Runtime task instances created while interacting with an agent
+- **context** - Runtime conversation/task context identifiers used during calls
 ### Paying with x402
 
 When **you** call an API or an A2A agent and receive HTTP 402 Payment Required, the SDK parses payment options and can pay (EVM) and retry the request. This is the *caller* flow—paying for a request you make—distinct from declaring "x402 support" on your agent card (which means your agent accepts payment from others).
 
 ### Calling agents via A2A
 
-The SDK can also **invoke** A2A agents: send messages, list and load tasks, and interact with task handles. This is the *caller* side—using the agent's `a2a` endpoint URL to make requests—separate from *advertising* your own A2A endpoint on your agent card.
+The SDK can also **invoke** A2A agents: send messages, list and load tasks, and interact with task handles. This is the *caller* side—using `agent.a2aEndpoint`, `summary.a2a`, or URL input with `sdk.createA2AClient(...)`—separate from *advertising* your own A2A endpoint on your agent card.
 
 ## Trust Models
 

src/content/docs/2-usage/2-10-a2a/index.md

@@ -148,6 +148,12 @@ if (result.x402Required) {
 
 See the SDK reference for full option types. The minimal examples above work without options.
 
-## Using an AgentSummary from search
+## Using AgentSummary or URL
 
-When you have an **Agent** (from `loadAgent`), call `messageA2A`, `listTasks`, and `loadTask` on it directly. When you have an **AgentSummary** (e.g. from `searchAgents`) and no full Agent, use `sdk.createA2AClient(summary)` to get a client that resolves the A2A endpoint from `summary.a2a` and exposes the same methods.
+When you have an **Agent** (from `loadAgent`), call `messageA2A`, `listTasks`, and `loadTask` on it directly.
+
+When you do not have a full `Agent`, use `sdk.createA2AClient(...)`:
+
+- `sdk.createA2AClient(summary)` resolves from `summary.a2a`
+- `sdk.createA2AClient("https://assistant.example.com")` resolves from a base URL
+- `sdk.createA2AClient("https://assistant.example.com/.well-known/agent-card.json")` uses a direct agent-card URL

src/content/docs/2-usage/2-11-x402/index.md

@@ -53,6 +53,18 @@ if (result.x402Required) {
 </TabItem>
 </Tabs>
 
+## A2A and MCP
+
+The same x402 flow applies to both protocol runtimes:
+
+- **A2A:** handle `x402Required` from `messageA2A`, `listTasks`, `loadTask`, then call `x402Payment.pay()`.
+- **MCP:** if an MCP endpoint is payment-gated, use the same pay-and-retry flow in your MCP runtime request pipeline.
+
+See:
+
+- [A2A usage](/2-usage/2-10-a2a/#when-the-agent-returns-402)
+- [MCP usage](/2-usage/2-12-mcp/#when-mcp-returns-402)
+
 ## Result type
 
 - **Success:** The return value is the parsed response body (e.g. JSON). No `x402Required` property.

src/content/docs/2-usage/2-12-mcp/index.md

@@ -0,0 +1,135 @@
+---
+title: "MCP"
+description: "Call agents via MCP tools, prompts, and resources"
+---
+Use the SDK to call MCP endpoints exposed by agents. You can create MCP clients from an `Agent`, an `AgentSummary`, or a URL string.
+
+## Create an MCP client
+
+<Tabs>
+<TabItem label="Python">
+
+```python
+# From URL
+mcp = sdk.createMCPClient("https://mcp.example.com/mcp")
+
+# From AgentSummary (e.g. search result)
+summary = sdk.searchAgents({"hasMCP": True})[0]
+mcp2 = sdk.createMCPClient(summary)
+
+# From loaded Agent
+agent = sdk.loadAgent("84532:1298")
+mcp3 = sdk.createMCPClient(agent)  # equivalent runtime handle to agent.mcp
+```
+
+</TabItem>
+<TabItem label="TypeScript">
+
+```ts
+// From URL
+const mcp = sdk.createMCPClient('https://mcp.example.com/mcp');
+
+// From AgentSummary (e.g. search result)
+const [summary] = await sdk.searchAgents({ hasMCP: true });
+const mcp2 = sdk.createMCPClient(summary);
+
+// From loaded Agent
+const agent = await sdk.loadAgent('84532:1298');
+const mcp3 = sdk.createMCPClient(agent); // equivalent runtime handle to agent.mcp
+```
+
+</TabItem>
+</Tabs>
+
+**URL semantics:** MCP URL is treated as the strict direct endpoint (no `/.well-known` discovery).
+
+## Use tools, prompts, and resources
+
+<Tabs>
+<TabItem label="Python">
+
+```python
+tools = mcp.tools.list()
+result = mcp.tools.call("weather_tool", {"city": "Lisbon"})
+
+prompts = mcp.prompts.list()
+prompt = mcp.prompts.get("daily_briefing", {"city": "Lisbon"})
+
+resources = mcp.resources.list()
+templates = mcp.resources.templates()
+content = mcp.resources.read("resource://weather/lisbon")
+```
+
+</TabItem>
+<TabItem label="TypeScript">
+
+```ts
+const tools = await mcp.tools.list();
+const result = await mcp.tools.call('weather_tool', { city: 'Lisbon' });
+
+const prompts = await mcp.prompts.list();
+const prompt = await mcp.prompts.get('daily_briefing', { city: 'Lisbon' });
+
+const resources = await mcp.resources.list();
+const templates = await mcp.resources.templates();
+const content = await mcp.resources.read('resource://weather/lisbon');
+```
+
+</TabItem>
+</Tabs>
+
+## When MCP returns 402
+
+Some MCP servers may require payment for specific operations. In that case, use the x402 flow (`result.x402Required` then `x402Payment.pay()`/`payFirst()`) and retry with the paid request result.
+
+<Tabs>
+<TabItem label="Python">
+
+```python
+# Generic x402-aware request flow (useful when your MCP endpoint is payment-gated)
+result = sdk.request({
+    "url": "https://mcp.example.com/mcp",
+    "method": "POST",
+    "headers": {"content-type": "application/json"},
+    "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"
+})
+
+if result.x402Required:
+    paid = result.x402Payment.pay()  # pays and retries
+    print(paid)
+else:
+    print(result)
+```
+
+</TabItem>
+<TabItem label="TypeScript">
+
+```ts
+// Generic x402-aware request flow (useful when your MCP endpoint is payment-gated)
+const result = await sdk.request({
+  url: 'https://mcp.example.com/mcp',
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
+});
+
+if (result.x402Required) {
+  const paid = await result.x402Payment.pay(); // pays and retries
+  console.log(paid);
+} else {
+  console.log(result);
+}
+```
+
+</TabItem>
+</Tabs>
+
+For full x402 options and helpers, see [x402 usage](/2-usage/2-11-x402/).
+
+## Notes
+
+- For loaded agents, you can use `agent.mcp` directly.
+- Discovery metadata (`mcpTools`, `mcpPrompts`, `mcpResources`) helps routing/filtering; runtime calls are performed against live endpoints.
+- If a runtime flow requires payment, use the x402 handling described in [x402 usage](/2-usage/2-11-x402/).
+
+For method signatures and detailed return types, see [SDK API — Runtime Client Methods](/5-reference/5-1-sdk/#runtime-client-methods).

src/content/docs/2-usage/2-2-configure-agents/index.md

@@ -246,6 +246,8 @@ agent.removeEndpoints();
 
 ## Wallet Configuration
 
+For runtime protocol invocation (calling other agents), see [A2A usage](/2-usage/2-10-a2a/) and [MCP usage](/2-usage/2-12-mcp/).
+
 ### Default behavior (wallet is set to the owner by default)
 
 Per ERC-8004, `agentWallet` is **initially set to the agent owner’s address**.
@@ -721,7 +723,7 @@ agent = sdk.createAgent(
 
 # Set endpoints
 agent.setMCP("https://mcp.example.com/")
-agent.setA2A("https://a2a.example.com/agent.json")
+agent.setA2A("https://a2a.example.com/agent-card.json")
 agent.setENS("myagent.eth")
 
 # Set trust models
@@ -766,7 +768,7 @@ const agent = sdk.createAgent(
 
 // Set endpoints (async in TypeScript)
 await agent.setMCP('https://mcp.example.com/');
-await agent.setA2A('https://a2a.example.com/agent.json');
+await agent.setA2A('https://a2a.example.com/agent-card.json');
 agent.setENS('myagent.eth');
 
 // Set trust models

src/content/docs/3-examples/3-6-mcp/index.md

@@ -0,0 +1,92 @@
+---
+title: "MCP"
+description: "Runtime MCP example: tools, prompts, resources, and x402 handling"
+---
+This example shows a complete MCP runtime flow: create a client, inspect capabilities, call a tool, and handle payment-gated endpoints with x402.
+
+<Tabs>
+<TabItem label="Python">
+
+```python
+from agent0_sdk import SDK
+import os
+
+sdk = SDK(
+    chainId=84532,
+    rpcUrl=os.getenv("RPC_URL"),
+    signer=os.getenv("PRIVATE_KEY"),
+)
+
+# 1) Create MCP client (URL / summary / agent all supported)
+mcp = sdk.createMCPClient("https://mcp.example.com/mcp")
+
+# 2) Inspect server capabilities
+tools = mcp.tools.list()
+prompts = mcp.prompts.list()
+resources = mcp.resources.list()
+
+# 3) Call a tool
+tool_result = mcp.tools.call("weather_tool", {"city": "Lisbon"})
+print(tool_result)
+
+# 4) x402-aware fallback for payment-gated MCP endpoints
+result = sdk.request({
+    "url": "https://mcp.example.com/mcp",
+    "method": "POST",
+    "headers": {"content-type": "application/json"},
+    "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"
+})
+if result.x402Required:
+    paid = result.x402Payment.pay()
+    print(paid)
+else:
+    print(result)
+```
+
+</TabItem>
+<TabItem label="TypeScript">
+
+```ts
+import { SDK } from 'agent0-sdk';
+
+const sdk = new SDK({
+  chainId: 84532,
+  rpcUrl: process.env.RPC_URL ?? '',
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+// 1) Create MCP client (URL / summary / agent all supported)
+const mcp = sdk.createMCPClient('https://mcp.example.com/mcp');
+
+// 2) Inspect server capabilities
+const tools = await mcp.tools.list();
+const prompts = await mcp.prompts.list();
+const resources = await mcp.resources.list();
+
+// 3) Call a tool
+const toolResult = await mcp.tools.call('weather_tool', { city: 'Lisbon' });
+console.log(toolResult);
+
+// 4) x402-aware fallback for payment-gated MCP endpoints
+const result = await sdk.request({
+  url: 'https://mcp.example.com/mcp',
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
+});
+if (result.x402Required) {
+  const paid = await result.x402Payment.pay();
+  console.log(paid);
+} else {
+  console.log(result);
+}
+```
+
+</TabItem>
+</Tabs>
+
+Notes:
+
+- MCP URL input is strict direct endpoint semantics.
+- For loaded agents, `agent.mcp` is an equivalent runtime MCP handle.
+- For full usage docs, see [Usage: MCP](/2-usage/2-12-mcp/).