This repository contains the reference implementation of the source code behind the public Model Context Protocol (MCP) server hosted at:
https://swen.ia.br/api/mcpSWEN.AI is a Brazilian portal covering AI news, model benchmarks, tools and tutorials. This MCP server exposes that data to AI agents and MCP-compatible clients (Claude, Claude Code, etc.) with no API key required (IP-based rate limiting only).
The files here are copied verbatim from our private production monorepo so that developers can read, audit, and understand exactly what the hosted endpoint does. Authentication, rate-limiting, and infrastructure code are intentionally not included — see Security below.
To use the server, connect your MCP client directly to the hosted endpoint; there is nothing to install or run locally.
{
"mcpServers": {
"swen-ai": {
"url": "https://swen.ia.br/api/mcp"
}
}
}Related MCP server: claude-wilder-mcp
Tool | Description |
| Search/list published AI news articles |
| Fetch a single news article by slug |
| List tracked AI models |
| Fetch a single AI model by slug |
| Get the canonical Artificial Analysis Intelligence Index ranking |
| Search/list AI tools in the directory |
| List tutorials |
Every tool is a thin wrapper: it validates input, calls a fetchers.ts
function to read from Postgres (via Supabase's REST API using the public
anon key), maps the row to a stable public contract (mappers.ts /
types.ts), and returns JSON.
src/lib/api-v1/
mcp-server.ts tool registration (the 7 tools above)
fetchers.ts data-fetching functions (reads only, public anon key)
mappers.ts DB row → public contract mapping
types.ts public contract types (NewsItem, ModelItem, ...)
src/lib/ranking/
fetch-aa.ts canonical Artificial Analysis ranking logic (dedup + sort)
src/lib/benchmark/
freshness.ts filters out stale benchmark scores
src/lib/i18n/
config.ts locale constants used by the mappersThese are copied byte-for-byte from the production repo. They are kept in sync manually; they may lag the deployed version slightly.
REST API docs (API key required, higher rate limits): https://swen.ia.br/developers
Full portal: https://swen.ia.br
This repo deliberately excludes:
auth.ts — API key validation and rate-limiting logic
key-crypto.ts — API key hashing
Any environment variable, credential, or internal Supabase project
reference beyond the two values that are public by design:
NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY (already
shipped in every page's browser bundle on swen.ia.br; access is governed
by Postgres Row Level Security, not by keeping this value secret).
If you believe you've found a security issue with the hosted endpoint, please report it privately rather than opening a public issue.
MIT — see LICENSE.
The current AI model intelligence ranking (Artificial Analysis Intelligence Index), deduplicated by model family — one entry per model at its best configuration. Identical ordering to swen.ia.br/ranking and the SWEN.AI iOS app.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 30) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses meaningful behavioral traits: deduplication, one entry per model at best configuration, and identical ordering to other sources. However, it does not mention safety, response format, or rate limits, leaving some gaps beyond what the description alone should cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose, followed by relevant detail about deduplication and ordering consistency. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description provides sufficient context: what the ranking is, how entries are selected (deduplicated, best configuration), and ordering reference. Minor gaps like default sorting direction or response format are acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' is fully described in the schema (100% coverage), so the description need not repeat it. The description adds some context about deduplication which relates to what limit controls (number of entries), but this is not explicitly tied to the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides the current AI model intelligence ranking, with specifics about deduplication and source (Artificial Analysis Intelligence Index). It distinguishes itself from a generic model list by emphasizing ranking and deduplication, but does not explicitly differentiate from siblings like list_ai_models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool vs alternatives such as get_model or list_ai_models. It implies usage by naming the purpose, but lacks explicit context, exclusions, or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single AI model by slug: pricing, context window, speed.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Model slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the tool's return fields (pricing, context window, speed) but does not mention error behavior (e.g., invalid slug), authentication requirements, rate limits, or the exact output structure. For a read operation, this is minimal but not dangerously opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action ('Get a single AI model') and includes essential details (by slug, pricing, context window, speed). Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description covers the basic purpose and return values. However, it lacks usage guidance and behavioral caveats (e.g., what happens if the slug is not found). It is adequate but not fully complete for an AI agent making invocation decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the only parameter 'slug' is described as 'Model slug'). The description confirms the filtering mechanism ('by slug') but adds no new semantic detail about the parameter beyond what the schema already provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single AI model by slug' with specific return fields (pricing, context window, speed). This distinctly differentiates it from sibling tools like list_ai_models, which likely retrieves multiple models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific slug and need details for one model, but it does not explicitly state when to prefer this over list_ai_models or other siblings. No exclusion or alternative guidance is provided beyond the implicit 'single' vs 'list' contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single AI news article by slug.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Article slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the action ('Get') and that it returns a single article, but does not mention return structure, error behavior, permissions, or other side effects. Minimal behavioral context beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. It is front-loaded with the purpose and includes the essential qualifier ('single', 'by slug'). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-slug tool, the description provides the core action and parameter. However, with no output schema and no annotations, it lacks details about return values, error handling, or prerequisites, making it minimally viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with a description for the slug parameter ('Article slug'). The tool description adds no additional meaning beyond restating 'by slug', so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('AI news article') with a clear scope ('single' and 'by slug'). It distinguishes itself from sibling tools like search_news, which is for searching, and list_tutorials, which lists tutorials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific slug and want one article, but it does not explicitly state when to use this tool versus search_news or other alternatives. There is no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List AI model catalog: pricing, context window, speed. From SWEN.AI benchmark database.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 50) | |
| offset | No | Pagination offset (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the information payload (pricing, context window, speed) and data source, but does not mention pagination, rate limits, or any side effects. The 'List' verb implies a read-only operation, though this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences with no redundancies. It states the action, key fields, and source in a compact format, earning high marks for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description names the key fields (pricing, context window, speed) to convey the return structure. It omits pagination defaults and sorting, but for a simple list tool with optional limit/offset, these are minor gaps. The source context adds completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (limit, offset) with clear descriptions and defaults, so the description need not add parameter-level detail. The description adds no semantics beyond the schema, matching the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List AI model catalog') and identifies the specific data included (pricing, context window, speed). This distinguishes it from sibling tools like get_model, which likely retrieves a single model, and search_tools, which searches the general tool catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a browsing use case ('List AI model catalog') and the source (SWEN.AI benchmark database), but does not explicitly state when to use this tool versus alternatives like get_model. There are no exclusions or alternative guidance, but the purpose is clear enough for basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tutorials and guides directory. From SWEN.AI.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 30) | |
| offset | No | Pagination offset (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only says 'Tutorials and guides directory. From SWEN.AI.' It does not disclose pagination, response format, or any other behavioral specifics beyond implying a list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, but 'From SWEN.AI' adds provenance rather than functional info, and the noun phrase could be more grammatically complete. Still, it is two short sentences with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is too sparse to be complete. It doesn't mention what tutorial data is returned, how pagination works, or any limitations, leaving the agent to infer from the name and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for limit and offset, so the schema fully documents both parameters. The description adds no parameter information, matching the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Tutorials and guides directory' is a noun phrase that implies the tool lists tutorials/guides but lacks an explicit verb like 'list' or 'retrieve'. It differentiates from sibling tools by topic but does not clearly state the action or scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. The description gives no context about use cases, filtering, or relationship to sibling tools like search_news or list_ai_models.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent AI news articles from SWEN.AI (Brazilian AI news portal). Returns summary + canonical link, never the full article body.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20) | |
| offset | No | Pagination offset (default 0) | |
| category | No | Filter by category, e.g. "Inteligência Artificial" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the tool returns only a summary and canonical link, and never the full body, which is a key behavioral constraint. It does not mention response ordering, pagination details, or rate limits, but for a simple list tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and immediately states the main action, followed by a concise note about the return type. Every word adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three optional parameters and no output schema, the description covers the essential aspects: what it does, the source, and the shape of the return value (summary + link). It lacks detailed response field documentation, but the given hints are sufficient for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all three parameters (limit, offset, category) with clear explanations and defaults. The tool description adds no extra parameter-level meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies a verb ('List'), a resource ('recent AI news articles'), and a source ('SWEN.AI'), making the tool's purpose unambiguous. It further distinguishes itself from sibling tools by noting it returns 'summary + canonical link, never the full article body', which directly contrasts with a potential article-fetching tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (listing recent AI news from SWEN.AI) and an implicit exclusion ('never the full article body'), which signals not to use it for full-article retrieval. However, it does not explicitly name alternative tools for that purpose, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI tools directory: pricing, ratings, categories. From SWEN.AI.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 50) | |
| offset | No | Pagination offset (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral context. It only lists content categories and provenance; it does not disclose whether the operation is read-only, how results are returned, pagination behavior, or any search/filter limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, with no redundant elaboration. The provenance note 'From SWEN.AI' is not strictly functional but does not meaningfully hurt conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two documented pagination parameters, and the description conveys the domain and key return aspects. However, without an output schema or any behavioral/usage detail, an agent may be uncertain about the exact response shape and how 'search' operates without a query parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because limit and offset both have descriptions and constraints. The tool description does not add meaning beyond the schema, but the schema fully documents the pagination parameters, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool as an AI tools directory with pricing, ratings, and categories, making the resource and content clear. It lacks an explicit verb but the name and title convey the search/list intent, and it is distinguishable from news or model siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus related siblings like list_ai_models or search_news. It does not mention alternatives, exclusions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_intelligence_rankingget_modelget_news_articlelist_ai_modelslist_tutorialssearch_newssearch_toolsScored across 7 tools
Each tool targets a distinct resource: model, tool, tutorial, news, or ranking. The model-related tools (get_model, list_ai_models, get_intelligence_ranking) are clearly differentiated by purpose, and search_tools vs search_news are separated by the object being searched.
All tool names follow a consistent verb_noun pattern using snake_case. The verbs (get, search, list) are applied predictably according to the action: get for single items, search for queries, and list for full catalogs or directories.
With 7 tools, the server is well-scoped for its domain covering models, tools, tutorials, and news. Each tool serves a clear purpose without redundancy, fitting comfortably within the ideal 3-15 range.
The news and model sections are complete with list/search and get operations, but tutorials only have a list (no get tutorial by slug) and tools only have search (no get tool by ID). These are minor gaps that agents can work around using the existing search/list results.
AI-powered news intelligence — 21 tools for personalized monitoring, briefings, and semantic search
8-tool AI web intelligence suite: search, scrape, screenshot, SEO, docs, crypto, code.
Live AI trend radar: trending AI topics, why-trending signals, daily digests. No API key.
Market intelligence for the AI agent economy: rankings, trust signals, liveness. 13 tools.
