How Agent-Native Integrates with MCP (Model Context Protocol): Complete Implementation Guide

Agent-Native integrates with MCP through a built-in connector that mounts an HTTP endpoint at /_agent-native/mcp, automatically exposes actions as protocol tools, and renders embedded React components via the mcpApp metadata field.

Agent-Native is an open-source framework for building AI-native applications. According to the BuilderIO/agent-native source code, the framework provides first-class support for the Model Context Protocol by implementing a server-side plugin system that transforms every application into an MCP host.

The MCP Server Plugin: Mounting the Endpoint

The integration starts with a dedicated server plugin that instantiates the MCP host. In templates/plan/server/plugins/00-mcp.ts, the framework imports mountMCP from @agent-native/core/mcp and registers the protocol endpoint.

This plugin creates the HTTP route /_agent-native/mcp (e.g., https://plan.agent-native.com/_agent-native/mcp), which becomes the single entry point for all MCP clients.

// templates/plan/server/plugins/00-mcp.ts
import { mountMCP } from "@agent-native/core/mcp";

export const mcpPlugin = async () => {
  // Mount the MCP server at /_agent-native/mcp
  await mountMCP({ basePath: "/_agent-native/mcp" });
};

Exposing Actions as MCP Tools

Once the endpoint is active, Agent-Native automatically surfaces actions defined under templates/plan/actions/* as callable MCP tools. Each action uses the defineAction helper from @agent-native/core/actions.

Automatic Action Discovery

The framework scans the actions directory and registers each export as an available tool. When an external MCP client (such as Claude, ChatGPT, or a custom host) invokes the action, the framework routes the request to the corresponding handler.

Embedding UI with mcpApp

Actions can expose a dedicated UI for MCP contexts by adding the mcpApp field to their definition. This field contains an embedApp function that returns a React component, allowing the MCP host to render the interface inline.

// templates/plan/actions/create-visual-plan.ts
import { defineAction } from "@agent-native/core/actions";

export const createVisualPlan = defineAction({
  name: "create-visual-plan",
  // action implementation …
  handler: async (input) => { /* … */ },

  // MCP metadata – renders a React view when called from an MCP host
  mcpApp: {
    embedApp: () => import("@/app/components/VisualPlanEditor"),
  },
});

When an external agent calls this action, it receives the result alongside the UI component defined in mcpApp, which the host can render directly.

Skill Metadata and Discovery

The MCP URL is baked into the application’s skill descriptor at templates/plan/agent-native.app-skill.json. This JSON file includes an "mcpUrl" field that points to the mounted endpoint, enabling external agents to discover the MCP capabilities automatically.

{
  "name": "visual-plan",
  "mcpUrl": "https://plan.agent-native.com/_agent-native/mcp"
}

Detecting MCP Context in the UI

Components can detect whether they are running inside an MCP embed surface using helper functions. In templates/plan/app/lib/mcp-embed.ts, the isMcpEmbedSurface utility checks for the presence of window.__MCP_EMBED__.

// templates/plan/app/lib/mcp-embed.ts
export const isMcpEmbedSurface = (): boolean =>
  typeof window !== "undefined" && !!window.__MCP_EMBED__;

This allows the UI to adjust its behavior—such as hiding navigation bars or rendering simplified views—when displayed within an MCP host.

Two-Way Integration: Calling External Agents

The integration works bidirectionally. While the app exposes its own actions as MCP tools, it can also call external MCP hosts. External agents request actions via the standard MCP endpoint, receive the JSON result, and can render the returned mcpApp UI inline.

// External agent (e.g., Claude Code)
const result = await fetch(
  "https://plan.agent-native.com/_agent-native/mcp/create-visual-plan",
  { method: "POST", body: JSON.stringify({ /* input */ }) }
).then((r) => r.json());

// If the action returned a `mcpApp`, the agent can embed it:
if (result.mcpApp) {
  displayEmbeddedResult(result.mcpApp);
}

Summary

• Mounting: The server plugin at templates/plan/server/plugins/00-mcp.ts calls mountMCP to create the /_agent-native/mcp endpoint.
• Action Exposure: All actions in templates/plan/actions/* are automatically registered as MCP tools.
• UI Embedding: The mcpApp.embedApp field in action definitions renders React components inside MCP hosts.
• Discovery: The mcpUrl field in templates/plan/agent-native.app-skill.json enables automatic endpoint detection.
• Context Detection: Utilities like isMcpEmbedSurface in templates/plan/app/lib/mcp-embed.ts allow components to adapt to MCP environments.

Frequently Asked Questions

What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard that enables AI models to securely connect to external data sources and tools. It defines a standardized way for agents to discover capabilities, invoke functions, and render UI components across different hosts.

How do I enable MCP in my Agent-Native application?

Enable MCP by creating a server plugin that imports mountMCP from @agent-native/core/mcp and calling it with your desired base path, typically in a file like templates/plan/server/plugins/00-mcp.ts. Ensure your agent-native.app-skill.json includes the mcpUrl field pointing to this endpoint.

Can I customize the UI shown to MCP clients?

Yes. Any action can expose a custom UI by adding the mcpApp field to its definition and providing an embedApp function that returns a React component. The component can also use isMcpEmbedSurface to detect when it is running inside an MCP host and adjust its layout accordingly.

Where is the MCP endpoint configured?

The endpoint path is configured in the server plugin at templates/plan/server/plugins/00-mcp.ts via the basePath parameter passed to mountMCP. The default and example configuration uses /_agent-native/mcp, and this URL is published in templates/plan/agent-native.app-skill.json for agent discovery.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}