MCP Agent Guide

Public operating guide for agents using the Robotico MCP server.

Robotico MCP is the structured API surface for agents that need humanoid robotics company data, robot/product data, source evidence, timeline intelligence, audit logs, and authorized contribution workflows.

Discovery

Resource	URL	Use
Human setup docs	/developers/mcp	Endpoint, token setup, exposed surfaces
Agent docs	/docs/agents	Site-wide agent operating rules
MCP registry metadata	server.json	MCP directory discovery
MCP server card	server-card.json	Server description, transport, capabilities
Markdown copy of this guide	`https://robotico.market/api/markdown?path=/docs/mcp`	Agent-readable page content

Connection

Use the hosted Streamable HTTP endpoint. Tokens are created from developer settings after signing in. Send the token as a bearer credential.

{
  "mcpServers": {
    "robotico": {
      "url": "https://robotico.market/mcp",
      "headers": {
        "Authorization": "Bearer rbt_..."
      }
    }
  }
}

Start each session with ping, then call tools/list. The live tool schemas are authoritative.

Read Playbook

Resolve the entity with entities.search, search_companies, or search_robots.
Use list tools for broad scans and detail tools for exact records.
Use get_robot without evidence for normal robot profile reads.
Use get_robot with include_evidence: true or robot.evidence only when field provenance is needed.
Use events.sources and events.changes only when a timeline event needs source or field-change detail.

Robot Maintenance Playbook

Task	Tool	Rule
Read profile	`get_robot`	Keep evidence opt-in by default
Read provenance only	`robot.evidence`	Filter by `field_path_prefix` when useful
Add source to correct value	`robot.link_source_to_field`	Use dot paths such as `specifications.height`
Patch low-risk facts	`update_robot`, `update_robot_profile`, `update_robot_specifications`	Include source URLs or field evidence when available
Manage media and aliases	`upload_robot_image`, `set_robot_image`, `add_robot_alias`	Do not change IDs or slugs
Stage risky changes	`create_robot_update_candidate`	Use for rename, status, classification, category, description, and variant changes
Review candidates	`list_robot_update_candidates`, `approve_robot_update_candidate`, `reject_robot_update_candidate`	Approval and rejection do not mutate robot profiles
Explain changes	`robot.audit_log`, `company.audit_log`, `entity.audit_log`	Use for traceability after writes

Timeline Event Playbook

Resolve related companies and robots before creating an event.
Call events.find_duplicates with title, summary, entity IDs, event date, and source URL.
If a likely duplicate exists, enrich the existing event instead of creating another canonical event.
If no likely duplicate exists, use events.create or create_event_candidate.
Provide a canonical HTTP or HTTPS source URL with a path or query and a JPEG screenshot of the exact page.
Add sources with events.add_source, link entities with events.link_company and events.link_robot, then review or publish according to role.

Risky Robot Candidate Operations

Operation	Preferred fields
`rename`	`proposed_name`
`status_change`	`proposed_status`
`classification_change`	`proposed_product_type` or `proposed_classification`
`category_change`	`proposed_category`
`description_rewrite`	`proposed_description`
`variant_merge`	`related_robot_ids` and/or structured `proposed_value`
`variant_split`	`related_robot_ids` and/or structured `proposed_value`

Robot Field Evidence

Robot evidence is keyed by field path. Common paths include tagline,status, capabilities, applications, and specification paths such as specifications.height.

Evidence sources can include source URL, publisher, source type, quoted excerpt, quote location, screenshot URL, page snapshot URL, stance, reliability, and extraction confidence. Use screenshots and page snapshots when a source page may change or when a reviewer needs visual confirmation.

Failure Handling

401: missing, malformed, revoked, disabled, or unverified-user token.
403: valid token without the role or ownership required for the tool.
429: rate limited. Back off and inspect Retry-After when present.
Validation errors mean the schema rejected the payload. Re-read tools/list and retry with the exact enum or field shape.