Remote MCP server

Let agents search catalogs, read consensus and save tier lists.

The tiero MCP server lets an AI assistant work with tiero for one person: find templates, read consensus rankings, and save tier lists or publish catalogs as that person. It is a remote server at https://tiero.io/mcp over Streamable HTTP, and people connect it with their tiero account. Nothing to install, and no API key to paste.

Connect

Add the server URL to any MCP client that supports remote servers with OAuth. The first request opens the tiero sign-in screen in a browser; after that the client keeps its tokens and refreshes them itself.

Claude Code

claude mcp add --transport http tiero https://tiero.io/mcp

Clients configured with JSON

{
  "mcpServers": {
    "tiero": {
      "type": "http",
      "url": "https://tiero.io/mcp"
    }
  }
}

Building your own client? Discovery follows the MCP authorization spec: an unauthenticated call to /mcp answers 401 with a WWW-Authenticate header that points at the protected resource metadata. Clients register themselves, use the authorization code flow with PKCE (S256 only) and send resource=https://tiero.io/mcp.

Path	What it is
`/mcp`	The MCP endpoint (Streamable HTTP, stateless). Needs a bearer token.
`/.well-known/oauth-protected-resource`	Protected resource metadata. Resource: https://tiero.io/mcp.
`/.well-known/oauth-authorization-server`	Authorization server metadata.
`/oauth/register`	Dynamic client registration (RFC 7591).
`/oauth/authorize`	The tiero sign-in and consent screen.
`/oauth/token`	Code exchange, refresh and revocation.

The consent screen shows the app's name, where its access goes (the redirect host) and an Unverified app label, because a self-registered app picks its own name. It lists the permissions the app asked for, all ticked; untick any you do not want to share. An app never gets a permission it did not ask for, and reading public data needs none. When an app asks for nothing in particular, the screen offers all four.

Scope	On the consent screen	Allows
`catalogs:write`	Publish templates	Create and update your catalog templates.
`media:write`	Upload images	Upload images to your account.
`lists:read`	Read your tier lists	Read your private and unlisted tier lists.
`lists:write`	Save tier lists	Create and update your tier lists.

People see and disconnect their apps under Account, Connected apps. Disconnecting, changing or resetting the password, suspension and account deletion all end the connection, and the next tool call fails. Access tokens are short lived; the refresh token lasts 30 days from sign-in.

Tools

Every tool returns JSON as structuredContent and as text. Reads return the same objects as the REST API, so a catalog is a CatalogDTO and a list is a ListDTO. Optional inputs end in ?.

Tool and input	Scope	What it does
`search_catalogs` `q?tag?game?owner?cursor?`	None	Search public catalog templates, 24 per page.
`get_catalog` `ownerslugcursor?`	None	Read a catalog and its items. Large catalogs add an items page.
`get_consensus` `ownerslug`	None	Read the community consensus board of a catalog.
`get_tier_list` `id`	lists:read for your non-public lists	Read a tier list.
`create_tier_list` `catalogtitletiersdescription?visibility?pool?`	lists:write	Save a new tier list as you.
`update_tier_list` `idrevisiontitle?description?visibility?tiers?pool?`	lists:write	Change one of your tier lists. Fields you leave out keep their values.
`upsert_catalog` `slugcatalogifRev?rightsAck?`	catalogs:write	Create or update one of your catalogs (catalog spec v1).
`upload_image` `filenamebase64`	media:write	Upload an image up to 2 MiB and get its media id.

upsert_catalog takes the same catalog spec as PUT /api/v1/catalogs/{slug}, with images as media ids from upload_image. Send ifRev to update only the revision you read, and rightsAck to confirm you hold the rights to the images.

Saving a tier list

create_tier_list takes the catalog as owner/slug and the tiers top to bottom, each with a label and the catalog item ids in order. tiero assigns tier ids t1 to tn and the default tier colors. Items you leave out stay in the pool. Get item ids from get_catalog.

create_tier_list arguments

{
  "catalog": "acme/cars",
  "title": "Best starter cars",
  "visibility": "public",
  "tiers": [
    { "label": "S", "items": ["comet", "banshee"] },
    { "label": "A", "items": ["sultan"] },
    { "label": "B", "items": [] }
  ]
}

update_tier_list needs the list's current revision (from get_tier_list or the create result), so two agents cannot overwrite each other. Lists saved this way show on tiero like any other list.

Errors

A tool that fails returns isError: true with the same error object as the API. Protocol problems (a missing or revoked token, the rate limit) are HTTP errors instead: 401 sends the client back to sign in, and 429 carries Retry-After.

A missing permission

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": "forbidden",
      "message": "Permission required",
      "details": { "requiredScope": "lists:write" }
    }
  }
}

Code	Meaning
`forbidden`	The connection lacks the scope in details.requiredScope. Reconnect and tick it.
`validation_failed`	The input broke a rule. details.issues lists each one; an unknown item id has code UNKNOWN_ITEM.
`revision_conflict`	The list changed since the revision you sent. Read it again and retry.
`not_found`	The catalog or list does not exist, or you cannot see it.
`account_suspended`	The account is suspended. Every tool refuses until it is restored.
`unauthorized`	The account was deleted. Tools stop working at once.
`daily_quota`	A daily upload or write quota ran out. Try again tomorrow.

Limits

Each person gets 120 MCP requests per 60 seconds across all their connected apps. Uploads are limited to 2 MiB of image data per call, and the account's media and catalog quotas apply the same way as on the API. The full numbers are on Limits.

Connect

Sign in and permissions

Tools

Saving a tier list

Errors

Limits