AIOZ Pin MCP Server

The AIOZ Pin MCP Server is a Model Context Protocol (MCP) (opens in a new tab) server for connecting MCP-compatible AI clients to AIOZ Pin IPFS pinning, NFT, gateway, and billing tools.

Use this page to review the tools exposed by the server and connect clients such as Cursor, Claude CLI, ChatGPT, or VS Code.

Configure MCP clients with https://mcp.aiozpin.network/sse?api_key=<BASE64URL_PINNING_CREDENTIALS>.

When to use this page

Use this page if you want to:

Pin existing IPFS content by CID.
Retrieve pin details, list pins, or unpin content.
Create and retrieve NFTs.
List public and premium gateways.
Review history usage data, monthly usage data, and top-up information.
Configure an MCP client to call AIOZ Pin tools.

Prerequisites

A valid AIOZ Pin (opens in a new tab) account.
A pinning API key and pinning secret key from the AIOZ Pin API Keys page (opens in a new tab).
An MCP-compatible client, such as Cursor, Claude CLI, ChatGPT connectors, or VS Code with GitHub Copilot Agent mode.

⚠️

Keep your pinning API key, pinning secret key, and encoded api_key private. Do not paste them into shared chats, public repositories, screenshots, or prompts that may be visible to other users.

Connection URL and `api_key`

Connect MCP clients to:

https://mcp.aiozpin.network/sse?api_key=<BASE64URL_PINNING_CREDENTIALS>

Create <BASE64URL_PINNING_CREDENTIALS> as follows:

Open the AIOZ Pin API Keys page (opens in a new tab) and copy your pinning API key and pinning secret key.

Create this JSON object with the exact field names shown below:

{
  "pinningApiKey": "<PINNING_API_KEY>",
  "pinningSecretKey": "<PINNING_SECRET_KEY>"
}

Encode the complete JSON string with base64url, without padding. The encoded result is the api_key value.

For example, with Node.js:

node -e 'const value={pinningApiKey:process.env.AIOZ_PINNING_API_KEY,pinningSecretKey:process.env.AIOZ_PINNING_SECRET_KEY}; console.log(Buffer.from(JSON.stringify(value)).toString("base64url"))'

Set AIOZ_PINNING_API_KEY and AIOZ_PINNING_SECRET_KEY in your local environment before running the command. Never commit either credential or the encoded api_key.

Available MCP tools

The server exposes tools for pinning, pin management, NFT operations, gateway discovery, and billing data. All tools use pinning credentials from the SSE api_key query parameter. Do not pass pinningApiKey or pinningSecretKey as tool arguments.

Pinning

`pin-by-cid`

Pins existing IPFS content by CID.

Parameter	Type	Required	Description
`hashToPin`	string	Yes	CID hash to pin
`metadataName`	string	No	Optional name metadata for pinned content

You can ask it to:

Pin a CID with a namePin CID bafkreigh2akiscaildcv7aac5u7bje5n with metadata name "homepage-hero".

Pin a document CIDPin CID bafybeigdyrztktxv5 with metadata name "q1-report.pdf".

`get-pin-details`

Gets pin details by pin ID.

Parameter	Type	Required	Description
`pinId`	string	Yes	Pin ID to fetch details

You can ask it to:

Inspect one pinGet details for pin ID <PIN_ID>.

Check a saved uploadShow me the pin details for <PIN_ID>.

`list-pins`

Lists pins with pagination and sorting options.

Parameter	Type	Required	Description
`offset`	number	No	Pagination offset, default 0
`limit`	number	No	Pagination limit, default 10
`pinned`	boolean	No	Filter by pinned state, default true
`sortBy`	string	No	Sort field, default name
`sortOrder`	string	No	Sort order (ASC or DESC), default ASC

You can ask it to:

List recent page of pinsList 10 pinned files starting at offset 0, sorted by name ASC.

Review unpinned recordsShow 20 unpinned records starting at offset 20, sorted by name DESC.

`unpin-file`

Removes a pinned file by pin ID.

Parameter	Type	Required	Description
`pinId`	string	Yes	Pin ID to remove

You can ask it to:

Remove one pinUnpin the file with pin ID <PIN_ID>.

Clean up a test pinRemove pin <PIN_ID> from my AIOZ Pin account.

NFT

`create-nft`

Creates an NFT by downloading a public HTTP(S) asset URL and uploading it with metadata.

Parameter	Type	Required	Description
`fileUrl`	string	Yes	Public HTTP(S) URL of the asset file
`metadata`	object	Yes	NFT metadata JSON object
`cid`	string	No	Optional existing asset CID

You can ask it to:

Create from a public fileCreate an NFT from https://example.com/artwork.png with metadata {"name":"Sunset #12","description":"Test artwork"}.

Create with an existing CIDCreate an NFT from https://example.com/cover.png using CID bafybeigdyrztktxv5 and metadata {"name":"Cover Art"}.

`get-nft`

Gets NFT details by NFT ID.

Parameter	Type	Required	Description
`nftId`	string	Yes	NFT ID to fetch

You can ask it to:

Inspect one NFTGet NFT details for NFT ID <NFT_ID>.

Verify a minted itemShow me the NFT record for <NFT_ID>.

`list-nfts`

Lists NFTs with pagination and sorting options.

Parameter	Type	Required	Description
`offset`	number	No	Pagination offset, default 0
`limit`	number	No	Pagination limit, default 10
`pinned`	string	No	Filter by pinned status: `all`, `true`, `false`
`sortBy`	string	No	Sort field: `created_at`, `size`, `name`
`sortOrder`	string	No	Sort direction: `ASC` or `DESC`

You can ask it to:

List all NFT recordsList 10 NFTs with pinned status all, sorted by created_at DESC.

Review pinned NFTsShow pinned NFTs starting at offset 20, sorted by name ASC.

Gateways

`list-gateways`

Lists public and premium gateways.

Parameter	Type	Required	Description
`offset`	number	No	Pagination offset, default 0
`limit`	number	No	Pagination limit, default 10
`type`	string	No	Gateway type: `Public`, `Premium`, or `all`

You can ask it to:

List public gatewaysList 10 Public gateways starting at offset 0.

Compare gateway optionsShow Premium gateways with limit 10 and offset 0.

Billing

`get-history-usage-data`

Gets history usage data details with pagination.

Parameter	Type	Required	Description
`offset`	number	No	Pagination offset, default 0
`limit`	number	No	Pagination limit, default 10

You can ask it to:

Review usage historyGet 10 history usage records starting at offset 0.

Page through usageShow history usage data with limit 25 and offset 25.

`get-top-up`

Gets top-up data details with pagination.

Parameter	Type	Required	Description
`offset`	number	No	Pagination offset, default 0
`limit`	number	No	Pagination limit, default 10

You can ask it to:

Review top-upsGet 10 top-up records starting at offset 0.

Page through top-upsShow top-up data with limit 25 and offset 25.

`get-month-usage-data`

Gets monthly usage data details with pagination.

Parameter	Type	Required	Description
`offset`	number	No	Pagination offset, default 0
`limit`	number	No	Pagination limit, default 10

You can ask it to:

Review monthly usageGet 10 monthly usage records starting at offset 0.

Page through monthly dataShow monthly usage data with limit 25 and offset 25.

Configure MCP clients

Choose the client you want to connect. All examples use the authenticated production SSE endpoint on mcp.aiozpin.network.

Cursor supports MCP through its MCP settings file.

Open MCP settings

Press Ctrl + Shift + P on Windows/Linux or Cmd + Shift + P on macOS.
Type Open MCP Settings and press Enter.
Cursor opens mcp.json, usually located at ~/.cursor/mcp.json.

Add the AIOZ Pin MCP Server

Add the aioz-pin-mcp-server entry inside mcpServers:

{
  "mcpServers": {
    "aioz-pin-mcp-server": {
      "url": "https://mcp.aiozpin.network/sse?api_key=<BASE64URL_PINNING_CREDENTIALS>"
    }
  }
}

Save and test

Save the file.
Open Cursor Chat with Ctrl + L.
Try a prompt such as: "List my AIOZ Pin pins using my pinning credentials".

Open MCP Settings in Cursor.

Add the AIOZ Pin MCP Server SSE endpoint.

Verify the MCP tools in Cursor Chat.

PreviousLLM Docs NextSDKs

AIOZ Pin MCP Server

When to use this page

Prerequisites

Connection URL and api_key

Available MCP tools

Pinning

pin-by-cid

get-pin-details

list-pins

unpin-file

NFT

create-nft

get-nft

list-nfts

Gateways

list-gateways

Billing

get-history-usage-data

get-top-up

get-month-usage-data

Configure MCP clients

Connection URL and `api_key`

`pin-by-cid`

`get-pin-details`

`list-pins`

`unpin-file`

`create-nft`

`get-nft`

`list-nfts`

`list-gateways`

`get-history-usage-data`

`get-top-up`

`get-month-usage-data`