Core Concepts

Key concepts you need to understand to use Universal API effectively.

Resource Types

Universal API has two types of resources:

MCP Servers

Model Context Protocol (MCP) servers provide tools, resources, and prompts that AI assistants can use. They're the primary way to extend Claude, Cline, and other MCP-compatible clients.

• Runtime: Node.js 20.x
• Protocol: MCP (Model Context Protocol) over Streamable HTTP
• Endpoint: POST https://mcp.api.universalapi.co/mcp/{serverId}
• Slug URL: POST https://mcp.api.universalapi.co/mcp/s/{owner}/{slug}

Example: A Google Suite MCP server that gives Claude access to Gmail, Calendar, and Drive.

AI Agents

Strands Agents are conversational AI assistants powered by AWS Bedrock. They can use tools, maintain multi-turn conversations, and perform complex tasks.

• Runtime: Python 3.12 with Strands SDK
• LLM: AWS Bedrock (Claude, Nova, Llama, Mistral)
• Endpoint: POST https://stream.api.universalapi.co/agent/{agentId}/chat
• Slug URL: POST https://stream.api.universalapi.co/agent/s/{owner}/{slug}/chat
• Features: Streaming responses, multi-turn conversations, tool use, session management

Example: A research agent that searches the web, analyzes documents, and summarizes findings.

Comparison

Feature	MCP Servers	Agents
Best for	AI assistant tools	Conversational AI
Runtime	Node.js	Python (Strands)
Stateful	No	Yes (conversations)
Streaming	No	Yes
LLM included	No	Yes (Bedrock)
Protocol	MCP	HTTP/SSE

Skills

Skills are reusable instruction sets based on the AgentSkills.io standard. A skill is a SKILL.md file with YAML frontmatter (name, description) and markdown instructions.

How they work:

• The AgentSkills plugin injects skill metadata into the system prompt
• The agent calls a skills tool to activate a skill on demand (progressive disclosure)
• Only activated skills' full instructions are loaded — saving tokens

Using skills in your agent:

from strands.vended_plugins.skills import AgentSkills

agent = Agent(model=model, plugins=[AgentSkills(skills=[
    "https://api.universalapi.co/skills/s/snowtimber/concise-answers/SKILL.md",
])])

See the Skills guide for details on creating and consuming skills.

Slugs & URLs

Every resource has two URL formats:

1. UUID-based: /mcp-admin/mcp-8bdb17c7-b4c7-4d... (always works)
2. Slug-based: /mcp-admin/s/snowtimber/my-server (human-readable)

Slugs are auto-generated from your alias + resource name:

• Alias: snowtimber
• Resource name: my-server
• Slug URL: /mcp-admin/s/snowtimber/my-server

INFO

You must set an alias before creating resources. Set it at universalapi.co/keys or via POST /user/alias.

Credits & Pricing

How Credits Work

Every API invocation costs credits. Your credit balance is tracked in your account.

Tier	Monthly Credits	Price
Free	100 (one-time)	$0
Starter	30,000/month	$29/month
Professional	600,000/month	$575/month

You can also purchase credit packs as one-time top-ups.

Credit Costs

Resource Type	Base Cost	Notes
MCP Server tools	1 credit	Minimum per tool call
Agent chat	2-20 credits	Varies by model and token usage

Agent costs depend on the Bedrock model used:

Model	Approximate Cost per Chat
Nova Micro	~1-2 credits
Nova Pro	~3-5 credits
Claude 3.5 Haiku	~2-4 credits
Claude Sonnet 4	~5-15 credits
Claude 3 Opus	~15-50 credits

Author Pricing

Resource authors can set additional per-invocation pricing on top of the base platform cost. This is how authors earn revenue.

{
  "authorPricing": {
    "creditsPerInvocation": 2,
    "description": "Premium web search with curated results"
  }
}

Author Earnings & Payouts

Authors earn revenue when others use their resources:

• Revenue split: Authors receive a share of the credits charged
• Minimum payout: $10 USD
• Payout schedule: Monthly (1st of each month)
• Payment method: Stripe Connect (direct deposit)

Set up payouts at universalapi.co/author → Payouts tab → Connect with Stripe.

Visibility

Resources can be public or private:

• Public: Visible to everyone, appears in search results and the marketplace
• Private: Only accessible by the author (requires authentication)

# Create a public MCP server
curl -s -X POST https://api.universalapi.co/mcp-admin/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serverName": "my-server",
    "description": "A public MCP server",
    "visibility": "public",
    "sourceCode": "..."
  }' | jq

Semantic Search

Universal API indexes all public resources using AI-powered semantic search (AWS Bedrock Titan Embeddings + S3 Vectors). Search by meaning, not just keywords:

# Find tools for sending email
curl -s "https://api.universalapi.co/search?q=send+email&type=mcp-tool" | jq

This returns relevant results even if the tool is named gmail_send — the semantic search understands the intent.

Search types: all, mcp, mcp-tool, agent

Knowledge Storage

Each user has a private file storage space for documents, PDFs, CSVs, and other files. Files are automatically indexed for semantic search.

• Upload files at universalapi.co/knowledge or via the API
• Search across files using natural language queries
• Use in agents — your files are accessible to your resources

See Knowledge for details.

Site Hosting

Each user gets a public website hosted at https://site.universalapi.co/{alias}/. Upload HTML, CSS, JavaScript, images, and other static files — they're instantly available on the web via CloudFront CDN.

• Upload files at universalapi.co/site or via the API
• Deploy from agents — AI agents can build and publish websites using MCP tools
• Public URLs — https://site.universalapi.co/{alias}/index.html
• Storage quotas — Free: 50MB, Starter: 1GB, Professional: 10GB

See Website Hosting for details.

API Response Format

All API responses follow a consistent structure:

{
  "data": { ... },
  "requestId": "req-xxx",
  "rootRequestId": "req-xxx",
  "parentRequestId": null
}

• data — The response payload
• requestId — Unique ID for this request (useful for debugging)
• rootRequestId — ID of the top-level request (for nested/chained calls)
• parentRequestId — ID of the parent request (if this was a nested call)