AIOZ Pin MCP Server Setup: llms.txt and 11 Tools Guide

An AIOZ Pin MCP server setup comes down to one question: should the assistant read about the API, or call it? AIOZ Pin documents both. The llms.txt file set gives a super intelligence assistant the API reference so it can write integration code. The MCP server gives a connected client 11 tools it can call directly against your account. This guide covers what each one contains, how to connect to them using the AIOZ Pin docs, and how to choose between them.

TL;DR:

• AIOZ Pin offers two ways to work with a super intelligence assistant: llms.txt files that the assistant reads, and a hosted MCP server whose tools it calls
• The llms.txt set is an index of about 2.7 KB, a full reference of about 14 KB, and eight section files, all plain text at aiozpin.network/docs
• The MCP server lives at mcp.aiozpin.network and exposes 11 tools across pinning, NFTs, gateways, and billing, with your credentials passed in the connection URL
• Three of the 11 tools change your account (pin-by-cid, create-nft, unpin-file), so give the assistant a narrowly scoped key
• Use llms.txt to build an integration, use the MCP server to operate your account from a conversation, and combine them when you want both

Two Ways to Connect: Reading Versus Calling

The two options solve different problems, and the AIOZ Pin docs list them on separate pages: LLM Docs and MCP Server.

The first option produces code you review and run. The second acts on your behalf as the conversation goes.

Option 1: llms.txt, the API Reference an Assistant Can Read

llms.txt is an open convention, described at llmstxt.org, for publishing documentation as plain text instead of rendered HTML. AIOZ Pin publishes:

• /docs/llms.txt, an index of about 2.7 KB that holds instructions for the assistant and links to each section
• /docs/llms-full.txt, the complete reference in one file of about 14 KB
• Eight section files at /docs/llms/<section>.md: api-keys, pinning, nft, gateways, users, billing, image-optimization, and pinning-services-api

Those sizes were measured on 2026-10-09 and will drift as the docs change.

The index opens with 12 numbered instructions written for the assistant. They cover the two auth methods (a JWT bearer token for admin and user endpoints, pinning_api_key and pinning_secret_key headers for pinning, NFT, gateway, and billing endpoints), the pin workflow (upload through POST /api/pinning, receive a CID, read it through a gateway URL), the public gateway format https://public.aiozpin.network/ipfs/{cid}, the rate limits of 180 requests per minute in general and 60 per minute for /users/ and /apiKeys/, and the official Node.js package @aioznetwork/aioz-pin-sdk. That is enough for an assistant to write a working upload function without guessing endpoint paths. The LLM Docs page shows the loading step for each tool:

• In Claude, attach the downloaded file to a chat in the Claude web app, or use it from Claude Code
• In Cursor, place the section files in your project and @-mention the one you need
• In ChatGPT, attach the downloaded file to a conversation
• In VS Code with GitHub Copilot, open the file in the editor and reference it in Copilot Chat with #

The docs recommend a single section file when you only need one area, because it keeps the context small: /docs/llms/pinning.md is enough for a pinning script. The index and full reference contain no MCP instructions, since the server has its own page.

Option 2: The MCP Server, Tools the Assistant Can Call

MCP, the Model Context Protocol, is an open standard for letting a super intelligence application call tools hosted by another server. The protocol architecture overview explains the general model. The AIOZ Pin MCP Server docs describe a hosted server for AIOZ Pin's IPFS pinning, NFT, gateway, and billing tools. Clients connect to:

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

You need a pinning API key and secret key from the API Keys page. The api_key value is a JSON object with the exact field names pinningApiKey and pinningSecretKey, encoded with base64url and no padding. The docs give this Node.js command, which reads the keys from environment variables:

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"))'

The server exposes 11 tools, and none of them accept credentials as arguments:

The docs include setup steps for Cursor, Claude CLI, ChatGPT, and VS Code with GitHub Copilot Agent mode. In Cursor, add the server to ~/.cursor/mcp.json:

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

In Claude CLI, you register it with SSE transport and read the encoded value from an environment variable:

claude mcp add --transport sse mcp-aioz-pin "https://mcp.aiozpin.network/sse?api_key=${PIN_MCP_API_KEY}"

The docs say to confirm the entry with claude mcp list. For ChatGPT, they describe adding a custom MCP server entry under Settings, Plugins, with the type set to Streamable HTTP and the same authenticated URL. A first prompt can be as plain as "List my AIOZ Pin pins using my pinning credentials."

Choosing Between Them

• To build an integration into your app, use llms.txt. The assistant writes code, you review it, and your application authenticates with its own key at runtime. Nothing in your account changes while you iterate.
• To operate your account from a conversation, use the MCP server. Pinning a known CID, checking a pin's details, or reading monthly usage becomes a sentence instead of an API call.
• For both, load a section file so the assistant understands the API, and connect the MCP server for quick checks. They are independent, so neither requires the other.

Whichever you choose, a pinning script that will run in production should still carry its own scoped key, as covered in AIOZ Pin API Keys: Auth, Scopes, and Secure Storage.

Keep the Connection URL Private

The MCP connection URL contains your pinning key and secret, only encoded. The docs warn to keep the key, the secret, and the encoded value out of shared chats, public repositories, and screenshots, and never to commit them.

Three tools can change the account: pin-by-cid adds a pin, create-nft adds an NFT, and unpin-file removes a pin. Removing a pin is the one to supervise, because an unpinned file is no longer kept online by the service. AIOZ Pin keys carry scopes, so you can issue a key with only the permissions you want the assistant to have. The MCP docs do not say which scope each tool needs, so test a new key against each tool you plan to use before relying on it.

Frequently Asked Questions

Does AIOZ Pin have an MCP server? Yes. The docs describe a hosted MCP server at mcp.aiozpin.network that exposes 11 tools for pinning, NFTs, gateways, and billing, with setup steps for Cursor, Claude CLI, ChatGPT, and VS Code.

What is llms.txt on AIOZ Pin? It is a plain-text version of the AIOZ Pin API reference at /docs/llms.txt, plus a full single-file version and eight section files, written so a super intelligence assistant can read the real endpoints, parameters, and auth patterns.

Can an assistant pin files for me through llms.txt? No. Reading llms.txt lets an assistant write code that calls the API, and you run that code. Only the MCP server lets a connected client call AIOZ Pin tools itself.

What can the AIOZ Pin MCP server do? It can pin an existing CID, show or list pins, unpin a file, create and retrieve NFTs, list public and premium gateways, and return usage history, monthly usage, and top-up records.

Which API key scopes does each MCP tool need? The documentation does not say. Create a key with limited scopes, try the tools you need, and widen the scopes only if a call is rejected.

Related Reading

• AIOZ Pin for Developers: API, SDK, and CLI Explained - the full API surface that llms.txt documents
• AIOZ Pin API Keys: Auth, Scopes, and Secure Storage - how to scope the key you give an assistant
• Getting Started with the AIOZ Pin Node.js SDK: A Guide - the SDK an assistant-written integration is likely to use
• Connecting a Super Intelligence Agent to AIOZ Stream: MCP Server or Tool Calling - the same reading-versus-calling question for AIOZ Stream
• AIOZ Storage llms.txt: Docs Built for Super Intelligence - how AIOZ Storage publishes its docs for assistants
• What Is an MCP Server? How Super Intelligence Agents Access Storage - a plain explanation of MCP

References

• AIOZ Pin Docs: LLM Docs
• AIOZ Pin Docs: MCP Server
• llmstxt.org: The /llms.txt Standard
• Model Context Protocol: Architecture overview