Skip to content

[Docs] Add MCP tool filtering, agent examples, and available tools list #8188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 6, 2025
Merged

[Docs] Add MCP tool filtering, agent examples, and available tools list #8188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 113 additions & 25 deletions apps/portal/src/app/ai/mcp/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,76 @@ https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>

Make sure to keep your secret key safe and never share it with anyone.

By default, all tools are available. You can filter the tools available by passing multiple `tool` query parameter.
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix grammatical error in tool filtering explanation.

"passing multiple tool query parameter" should be "passing multiple tool query parameters" (plural form).

Apply this diff to fix the grammar:

-By default, all tools are available. You can filter the tools available by passing multiple `tool` query parameter.
+By default, all tools are available. You can filter the tools available by passing multiple `tool` query parameters.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
By default, all tools are available. You can filter the tools available by passing multiple `tool` query parameter.
By default, all tools are available. You can filter the tools available by passing multiple `tool` query parameters.
🤖 Prompt for AI Agents 
In apps/portal/src/app/ai/mcp/page.mdx around line 20, the sentence "You can
filter the tools available by passing multiple `tool` query parameter." uses the
singular "parameter" incorrectly; change it to the plural "parameters" so the
line reads "You can filter the tools available by passing multiple `tool` query
parameters."


```http
https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>&tool=fetchWithPayment&tool=getWalletBalance
```

You can find all available tools at the bottom of this page.

## Usage with agents

Use your favorite agent framework to plug in the MCP server as a collection of tools for your agent. Refer to your agent framework's documentation for more information.

#### Example usage with langchain:

<Tabs defaultValue="typescript">

<TabsList>
<TabsTrigger value="typescript">TypeScript</TabsTrigger>
<TabsTrigger value="python">Python</TabsTrigger>
</TabsList>

<TabsContent value="typescript">

```typescript
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const mcpServers = {
thirdweb: {
url: `https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>`
}
};

// Connect to MCP servers and get tools
const client = new MultiServerMCPClient(mcpServers);
const tools = await client.getTools();

const agent = createReactAgent({
llm: model,
tools: tools,
});
await agent.invoke({messages: [{ role: "user", content: "create a server wallet called 'my-wallet'" }]})
```

</TabsContent>

<TabsContent value="python">

```python
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient(
{
"thirdweb": {
"url": "https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>",
}
}
)
tools = await client.get_tools()
agent = create_react_agent("openai:gpt-4.1", tools)
response = await agent.invoke({"messages": "create a server wallet called 'my-wallet'"})
```

</TabsContent>

</Tabs>

Once installed, you can use the entire thirdweb API with natural language.

## Usage with LLM clients

You can also use the MCP server on your own LLM client, like cursor, claude code and more. Refer to your LLM client's documentation for more information.
Expand Down Expand Up @@ -112,31 +182,6 @@ claude mcp add --transport http "thirdweb-api" "https://api.thirdweb.com/mcp?sec

</Tabs>

## Usage with agents

Use your favorite agent framework to plug in the MCP server as a collection of tools for your agent. Refer to your agent framework's documentation for more information.

#### Example usage with langchain:

```python
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient(
{
"thirdweb-api": {
"transport": "streamable_http",
"url": "https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>",
}
}
)
tools = await client.get_tools()
agent = create_react_agent("openai:gpt-4.1", tools)
response = await agent.ainvoke({"messages": "create a server wallet called 'my-wallet'"})
```

Once installed, you can use the entire thirdweb API with natural language.

## Example prompts

#### Managing server wallets
Expand Down Expand Up @@ -164,3 +209,46 @@ List my contracts
```
approve 100 USDC from treasury wallet to executor wallet
```

## Available tools

Currently, the following tools are available:

- `initiateAuthentication`
- `completeAuthentication`
- `linkAuthentication`
- `unlinkAuthentication`
- `getMyWallet`
- `listUserWallets`
- `createUserWallet`
- `listServerWallets`
- `createServerWallet`
- `getWalletBalance`
- `getWalletTransactions`
- `getWalletTokens`
- `getWalletNFTs`
- `signMessage`
- `signTypedData`
- `sendTokens`
- `listContracts`
- `deployContract`
- `readContract`
- `writeContract`
- `getContractTransactions`
- `getContractEvents`
- `getContractMetadata`
- `getContractSignatures`
- `getTransactionById`
- `listTransactions`
- `sendTransactions`
- `createPayment`
- `paymentsPurchase`
- `getPaymentHistory`
- `fetchWithPayment`
- `createToken`
- `listTokens`
- `getTokenOwners`
- `getBridgeChains`
- `convertFiatToCrypto`
- `bridgeSwap`
- `chat`
4 changes: 4 additions & 0 deletions apps/portal/src/app/payments/sidebar.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,10 @@ export const sidebar: SideBar = {
href: `${paymentsSlug}/x402/server`,
name: "Server Side",
},
{
href: `${paymentsSlug}/x402/agents`,
name: "Agents",
},
{
href: `${paymentsSlug}/x402/facilitator`,
name: "Facilitator",
Expand Down
87 changes: 87 additions & 0 deletions apps/portal/src/app/payments/x402/agents/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
import { OpenApiEndpoint } from "@doc";

# Agents

Easily create AI agents that can pay for any x402-compatible API calls.

## Using the MCP Server

The easiest way to equip your agents with the ability to pay for API calls is to use the [remote MCP server](/ai/mcp) and provide the tools to your agent.

The MCP server comes with all the tools by default, but you can filter the tools available by passing multiple `tool` query parameter.
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix grammatical error in tool filtering explanation.

Same issue as in the MCP documentation: "passing multiple tool query parameter" should be "passing multiple tool query parameters" (plural form).

Apply this diff to fix the grammar:

-The MCP server comes with all the tools by default, but you can filter the tools available by passing multiple `tool` query parameter.
+The MCP server comes with all the tools by default, but you can filter the tools available by passing multiple `tool` query parameters.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The MCP server comes with all the tools by default, but you can filter the tools available by passing multiple `tool` query parameter.
The MCP server comes with all the tools by default, but you can filter the tools available by passing multiple `tool` query parameters.
🤖 Prompt for AI Agents 
In apps/portal/src/app/payments/x402/agents/page.mdx around line 12, the
sentence uses the singular "query parameter" but should be plural; update the
sentence to read "passing multiple `tool` query parameters" so the grammar
correctly indicates multiple parameters.


In this example, we create a ReAct agent using LangChain and filter the MCP tools to `fetchWithPayment` and `getWalletBalance` as the only 2 tools we give our agent. You can view the full list of available tools [here](/ai/mcp#available-tools).

<Tabs defaultValue="typescript">

<TabsList>
<TabsTrigger value="typescript">TypeScript</TabsTrigger>
<TabsTrigger value="python">Python</TabsTrigger>
</TabsList>

<TabsContent value="typescript">

```typescript
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
model: "gpt-4.1",
});

const mcpServers = {
thirdweb: {
url: `https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>&tool=fetchWithPayment&tool=getWalletBalance`
}
};

// Connect to MCP servers and get tools
const client = new MultiServerMCPClient(mcpServers);
const tools = await client.getTools();

const agent = createReactAgent({
llm: model,
tools: tools,
prompt: "Use the fetchWithPayment tool to fetch any endpoint. Always pay in {{tokenAddress}}. Your wallet address is {{walletAddress}}."
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify template placeholder usage in agent prompts.

Both TypeScript and Python examples include prompt templates with {{tokenAddress}} and {{walletAddress}} placeholders, but the documentation doesn't explain what these should be replaced with or how users should obtain these values.

Users may be confused about:

  • What format tokenAddress should be in (contract address, symbol, etc.)
  • Whether walletAddress refers to their user wallet or server wallet
  • Whether these are meant to be replaced before runtime or if the agent should handle them dynamically

Consider adding a brief explanation before or after the code examples, such as:

Replace the template placeholders in the prompt:
- `{{tokenAddress}}`: The ERC-20 token contract address to use for payments (e.g., USDC on Base)
- `{{walletAddress}}`: Your wallet address (from user wallets or server wallets)

Or if these are meant to be dynamic runtime values, clarify how the agent should resolve them.

Also applies to: 67-67

});
```

</TabsContent>

<TabsContent value="python">

```python
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient(
{
"thirdweb": {
"url": "https://api.thirdweb.com/mcp?secretKey=<your-project-secret-key>&tool=fetchWithPayment&tool=getWalletBalance",
}
}
)
tools = await client.get_tools()
agent = create_react_agent("openai:gpt-4.1", tools, prompt="Use the fetchWithPayment tool to fetch any endpoint. Always pay in {{tokenAddress}}. Your wallet address is {{walletAddress}}.")
```

</TabsContent>
</Tabs>

## Using the API directly

You can also create your own MCP tool or wrap all external calls with the `/v1/x402/fetchWithPayment` endpoint to automatically handle payment flows when APIs return a `402 Payment Required` response.

Pass the target `url`, `method` and optional `from` wallet address to the endpoint that will complete the payment. The address should be one of your [user wallets](/wallets/users) or [server wallets](/wallets/server).

```bash
curl -X POST https://api.thirdweb.com/v1/payments/x402/fetch?url=https://api.example.com/premium&method=GET&from=0x1234... \
-H "Content-Type: application/json" \
-H "x-secret-key: <your-project-secret-key>" \
-d '{ ... }' # optional request body passed through to the url called.
```

<OpenApiEndpoint path="/v1/payments/x402/fetch" method="POST" />

Loading