ACAgentic Craft

Intermediate~20 minHazelJS

MCP Tool vs Skillgate Skill vs Direct API

Choose how HazelJS agents reach capabilities: curated Skillgate skills, MCP transport, or direct @Tool/API adapters—governance first.

Authors
editorial-team
Published
Last reviewed
Intended use case
Deciding how to expose HTTP/business capabilities to AgentRuntime without over-broad tool surfaces.
Evaluation date
2026-08-13

Criteria and weights

CriterionWeightDescription
Governance & curation0.3Ease of allow/deny, approval metadata, least privilege
Reuse across agents/hosts0.2
Developer experience0.2
Day-2 operations0.15
Cross-ecosystem protocol fit0.15

Options

Direct @Tool / API adapter

Best for: 1–10 domain tools owned by the app team (lookupOrder, createTicket)

Strengths

  • Fastest path for a few hand-written tools
  • Full control over schemas and idempotency
  • No OpenAPI/MCP indirection

Limitations

  • Does not scale cataloguing across large REST surfaces
  • Easy to forget policy metadata on each tool
  • Weak cross-host reuse

Skillgate skill (OpenAPI → ToolRegistry)

Best for: Exposing a governed slice of your HazelJS HTTP API to agents

Strengths

  • Opt-in curation from OpenAPI/module with report()
  • Metadata: requiresApproval, readOnly, capability, riskLevel
  • First-class Agent OS path into ToolRegistry + optional MCP export

Limitations

  • Requires disciplined include tags / classify flags
  • Still needs PolicyEngine + HITL for writes
  • Not a substitute for idempotent adapters

MCP tool server / client

Best for: Sharing curated skills with external MCP hosts, or importing external tool servers under host policy

Strengths

  • Standard discovery/transport across hosts
  • Can export curated ToolRegistry or consume external servers
  • Good for ecosystem tools outside your monolith

Limitations

  • No MCP-native allow-list API—curation is what you register
  • Easy to over-export and skip Agent OS policy
  • Auth and observation hygiene still your job

Architectural differences

**Direct @Tool** is code-owned capability in your DI module. **Skillgate** generates governed skills from OpenAPI/module and registers them onto ToolRegistry for a named agent. **MCP** is a transport/discovery protocol—HazelJS can serve a registry as MCP or consume MCP tools into the same ToolRegistry. Governance lives in curation + PolicyEngine, not in the protocol label.

Operational implications

Prefer Skillgate for first-party HTTP surfaces. Use direct @Tool for a handful of bespoke tools. Use MCP when you must interoperate with external hosts or import external servers—always behind the same budgets, guardrails, and HITL as local tools. Never run uncurated ‘all OpenAPI → MCP’ exports in production.

How to choose (HazelJS)

If you need…Prefer
A few domain tools with custom idempotencyDirect @Tool
Curated REST → agent skills with report()Skillgate
Cross-host protocol / external tool serversMCP on top of a curated registry

Related: /guides/skillgate-from-openapi-to-tool-registry, /guides/secure-mcp-servers-and-agent-tools, /patterns/tool-using-agent.

Composition

Production systems often combine all three: Skillgate for first-party HTTP, a few hand-written @Tools for odd cases, MCP export of the same curated registry for IDE/host interop. Keep one policy plane (PolicyEngine + budgets + HITL).

What this is not

Not a vendor bake-off of third-party MCP marketplaces. Not permission to skip guardrails because “it’s just MCP.”

Sources