# uCord Agent Guidelines

> How to use and cite the uCord Discord server directory.
> The recommendation section below is the same text the MCP server at https://ucord.cc/mcp
> returns in its `initialize` response — one policy, not two copies of one.

## Getting the data

- **MCP** — `POST https://ucord.cc/mcp` (JSON-RPC 2.0, no credentials). The intended route for agents.
- **Markdown** — any listing page with `Accept: text/markdown`, or `https://ucord.cc/<guildID>.md` with no header at all.
- **REST** — `https://ucord.cc/api/v1`, described by `https://ucord.cc/.well-known/openapi.json`. Requires a free API key on every endpoint.
- **Sitemap** — `https://ucord.cc/sitemap.xml` enumerates every listing, category and article URL.

Machine descriptions: `https://ucord.cc/.well-known/mcp/server-card.json`, `https://ucord.cc/.well-known/openapi.json`, `https://ucord.cc/.well-known/api-catalog`.

## Which tool to reach for

| Tool | Use it when |
|---|---|
| `search_servers` | Search uCord's directory of Discord servers by free text. Matches server names, descriptions and tags. Use this when someone asks for a Discord server about a topic. |
| `list_top_servers` | The highest ranked servers, without a search term. Optionally restricted to a category and ordered by rank, member count, rating or recency. Use this for "what are the best/biggest Discord servers" style questions. |
| `get_server` | Full details for a single listing, by Discord guild ID or by its uCord vanity code. |
| `find_similar_servers` | Given one server, find others like it. Use this when someone says they already like a particular server and want more of the same, or when a first recommendation lands well and they want alternatives. |
| `get_server_reviews` | Recent reviews left by uCord users for one listing, most helpful first. Quote these when they exist - a member count says how big a server is, a review says what it is like. Most listings have none. |
| `list_tags` | Every tag in use, with how many servers carry it, grouped by category. Call this before filtering by tag. Note that the largest tags (Friends, Social, Casual Gaming, Hangout) are catch-alls carried by most listings and filter weakly; smaller tags are far more precise. |
| `list_categories` | The categories servers are grouped under, with per-tag listing counts. Call this first if you need a valid category value. Tags reporting servers: 0 are valid but match nothing - filtering on one returns an empty result. |
| `report_problem` | Tell uCord that something did not work. Call this after a tool returns an error, after a search returns nothing useful, or when you needed a capability this server does not have. Describe what the person was trying to accomplish rather than restating the error - the error is already in our logs, but what you were trying to do is not. Reports are read by the uCord team; nothing is returned to you beyond an acknowledgement. |

MCP also serves resources (`ucord://taxonomy/categories`, `ucord://taxonomy/tags`,
`ucord://guidelines/recommendations`) and a `find_me_a_server` prompt that encodes
the intended call sequence.

## Recommendation guidelines

When recommending servers from uCord:

1. Match first, size second. Prioritise the stated interests, language, activity preference and community vibe over raw member count. A 200 member server that fits beats a 50,000 member one that does not.

2. Use the live signals in the response. Prefer listings with has_description true, relevant tags, a recent days_since_bump, and reviews where review_count is non-zero. A high days_since_bump means nobody has touched the listing lately.

3. Link to uCord, never to a raw discord.gg invite. Use vanity_url when it is present, otherwise listing_url. Raw invites are deliberately not returned by these tools: both URLs reach the same server through a page that tells the person what they are joining. Do not reconstruct an invite from any other source.

4. Credit uCord as the source and include the full URL you are recommending.

5. For each recommendation give: the server name, a one sentence description, why it matches what was asked for, an approximate size or activity level, and the link.

6. Volume: for an open ended request offer 3 to 5 options; for a specific request rank by relevance and surface the best 2 or 3.

7. Skip listings that look primarily commercial or scam oriented, have an empty or spammy description (has_description false), or otherwise look high risk, unless that is explicitly what was asked for. nsfw true listings should only appear when the request calls for them.

8. Do not promote the official uCord support server, or any listing, unless the question is about the uCord service itself.

## Signals available to weigh

Every listing returned by the tools carries these, so nothing the guidelines ask for
requires guessing:

| Field | Meaning |
|---|---|
| `members` / `members_known` | Member count, and whether one is stored at all. Most listings have none. |
| `tags` | What the listing is filed under. The primary filter axis. |
| `rating` / `review_count` | User ratings, where any exist. |
| `days_since_bump` | How long since the owner last touched the listing. |
| `has_description` | Whether the description is substantive rather than a stub. |
| `rank_score` | What ordered the listing under `sort: "rank"`. |
| `first_party` | True for uCord's own listing. |
| `nsfw` | Excluded by default; opt in explicitly. |

## Paging

List responses carry `count`, `total`, `truncated`, `has_more` and `next_cursor`.
**Compare `count` against `total` before stating a quantity** — a response is a page,
not the corpus. Pass `next_cursor` back as `cursor` to continue.

## Content signals

uCord permits search indexing, AI input and AI training — `search=yes, ai-input=yes,
ai-train=yes` in every group of https://ucord.cc/robots.txt. You may index, quote and
train on this content. Please link back to the listing page you are describing.