External Agent Integration

This page is for agents running outside this repository context (remote assistants, IDE agents, orchestration services).

Goal

Make external agents use both:

• skills/ for workflow and guardrails
• mantle-mcp for deterministic data and typed interfaces

The local skills/ path is backed by the mantle-xyz/mantle-skills Git submodule, and the actual skill folders live under skills/skills/.

Integration Checklist

1. Build and run MCP server:
   • npm install
   • npm run build
   • launch node dist/index.js with MANTLE_MCP_TRANSPORT=stdio
2. Register MCP server in agent runtime config.
3. Run npm run skills:init if the skills/ submodule has not been initialized yet.
4. Give agent read access to repository skills/ folder.
5. Require skill-first workflow before tool execution.
6. Require MCP outputs as final-answer evidence.

Skill-First Protocol (Required)

For every user task:

1. Select matching skill from skills/skills/*.
2. Read skills/skills/<skill-name>/SKILL.md.
3. Apply its checklist.
4. Execute relevant MCP tools/resources/prompts.

If no exact skill matches, external agent should:

1. Choose closest skill for risk controls.
2. State assumptions.
3. Continue with MCP-grounded execution.

MCP Execution Protocol (Required)

External agents should follow this sequence:

1. Discover:
   • listTools
   • listResources
   • listPrompts
2. Load context:
   • readResource for mantle://... URIs
   • getPrompt for workflow templates
3. Execute:
   • callTool with schema-valid arguments
4. Report:
   • cite tool outputs
   • do not invent addresses, balances, chain status, or token prices

Recommended Tool Order

1. Chain context: mantle_getChainInfo, mantle_getChainStatus
2. Canonical resolution: mantle_resolveAddress, mantle_resolveToken
3. Domain actions: account/token/defi/indexer/diagnostics tools
4. Error handling: use typed error payload fields (code, message, suggestion, details)

Minimal Safety Policy for External Agents

• Always resolve token/address before transaction-adjacent reasoning.
• Treat null price as unknown data.
• For custom endpoints, rely on built-in endpoint policy enforcement.
• Use diagnostics tools before declaring endpoint health.