# Register MCP Servers as Tools (/typescript-sdk/tools/mcp-tools)

Learn how to add and configure MCP tools for your agents



<SkillRule id="mcp-tools-registration" skills="typescript-sdk" title="Registering MCP Servers as Tools" description="How to register and configure MCP tools for your agents">
  MCP tools connect to external MCP servers, enabling integration with a wide ecosystem of tools and services. Registering them as tools is a two step process:

  ### Step 1: Get an MCP server URL

  You need access to an MCP server before you can use its tools. Learn about connecting to Native servers, using Composio, using Gram, or building Custom servers in the [MCP Servers tutorial](/tutorials/mcp-servers/overview).

  ### Step 2: Register the MCP server as a tool in your agent

  ```typescript
  import { subAgent, mcpTool } from "@inkeep/agents-sdk";

  // Register an existing MCP server as a tool
  const knowledgeBaseTool = mcpTool({
    id: "knowledge-base-tool",
    name: "knowledge_base",
    description: "Search the company knowledge base for information",
    serverUrl: "https://kb.yourcompany.com/mcp", // URL of your deployed MCP server
  });

  const qaAgent = subAgent({
    id: "qa-agent",
    name: "QA Agent",
    description: "Responsible for answering questions about the company knowledge base.",
    prompt: `You are a Question-Answer agent that can answer questions about the company knowledge base. You have access to the knowledge base tool to search for information.`,
    canUse: () => [knowledgeBaseTool],
  });
  ```

  ## Custom Usage Instructions

  You can provide custom instructions for how agents should use tools from an MCP server by adding a `prompt` field:

  ```typescript
  import { mcpTool } from "@inkeep/agents-sdk";

  const weatherTool = mcpTool({
    id: "weather-tool",
    name: "weather_api",
    description: "Get current weather information",
    serverUrl: "https://weather.example.com/mcp",
    prompt: `When using weather tools, always ask for the user's location first if not provided. 
             Format temperature responses in both Celsius and Fahrenheit for better user experience.
             Include weather alerts if any severe conditions are detected.`,
  });
  ```

  The custom prompt is provided to agents as usage guidelines for all tools from this server, helping them understand the specific context and best practices for using these tools.
</SkillRule>

<SkillRule id="mcp-tool-overrides" skills="typescript-sdk" title="MCP Tool Overrides" description="Customize how individual MCP tools appear to agents">
  ## Tool Overrides

  You can customize how individual tools from an MCP server appear to agents using tool overrides. This is useful for simplifying complex tools or providing better names and descriptions:

  ```typescript
  import { mcpTool } from "@inkeep/agents-sdk";
  import { z } from "zod";

  const apiTool = mcpTool({
    id: "complex-api-tool",
    name: "enterprise_api",
    description: "Enterprise API with many complex tools",
    serverUrl: "https://api.enterprise.com/mcp",
    toolOverrides: {
      // Override a specific tool by its original name
      "fetch_user_analytics_data_with_filters": {
        displayName: "get_user_stats", // Simpler name for agents
        description: "Get user statistics and analytics data", // Clearer description
        schema: z.object({
          userId: z.string().describe("User ID to fetch stats for"),
          timeframe: z.enum(["daily", "weekly", "monthly"]).describe("Time period for stats")
        })
      }
    }
  });
  ```

  ### Tool Override Options

  | Field         | Description                                                            |
  | ------------- | ---------------------------------------------------------------------- |
  | `displayName` | Custom name that agents will see (simpler than the original tool name) |
  | `description` | Custom description explaining what the tool does                       |
  | `schema`      | Simplified parameter schema with only the fields agents need           |

  <Note>
    Tool overrides are configured in the 

    [Visual Builder](/visual-builder/tools/mcp-servers#tool-overrides)

     for easier management, but can also be defined programmatically as shown above.
  </Note>

  <Note>
    Tip: When adding tools to an agent, you can also reference the tool in the agent's prompt to help the agent understand how to use the tool.
  </Note>
</SkillRule>

<SkillRule id="mcp-tool-auth" skills="typescript-sdk" title="MCP Tool Authentication" description="Authentication methods for MCP servers including API keys, OAuth, and custom headers">
  ## Authentication

  If your MCP server requires authentication, we support various authentication methods (via credentials):

  * **No Authentication** - For public APIs or internal services
  * **API Key** - For services requiring API keys
  * **Bearer Token** - For JWT or similar token-based authentication
  * **Token Authentication** - For custom token schemes
  * **OAuth Flows** - For standard OAuth 2.0 authentication
  * **OAuth 2.1 Flows** - For modern OAuth 2.1 "1-click" authentication

  For OAuth flows and OAuth 2.1 flows, it's recommended to use the [Visual Builder](/visual-builder/tools/mcp-servers) for easier configuration.

  See [Credentials](/typescript-sdk/credentials/overview) for detailed examples and implementation guidance for each authentication type.

  ### Custom Headers

  You can configure custom headers for your MCP server requests. Use credentials for sensitive information (API keys, tokens) and headers for non-sensitive metadata (user agent, version info, etc.).

  ```typescript
  import { mcpTool } from "@inkeep/agents-sdk";

  const customHeadersTool = mcpTool({
    id: "enterprise-api",
    name: "enterprise_data",
    description: "Enterprise API with custom headers",
    serverUrl: "https://enterprise.example.com/mcp",
    headers: {
      "User-Agent": "Inkeep-Agent/1.0",
      "X-Client-Version": "2024.1",
    },
  });
  ```
</SkillRule>

<SkillRule id="mcp-tool-selection" skills="typescript-sdk" title="Selecting MCP Tools" description="How to selectively enable tools from MCP servers">
  ## Selecting Tools

  <Tip>
    If some tools are sensitive (delete, write, payments, etc.), you can require explicit user approval before they run. See
    [Tool approvals](/typescript-sdk/tools/tool-approvals).
  </Tip>

  ### Selective Tool Activation

  Enable only specific tools from a server using MCP Server tool names in the `activeTools` field.

  ```typescript
  import { mcpTool } from "@inkeep/agents-sdk";

  const selectiveTool = mcpTool({
    id: "limited-server",
    name: "analytics_readonly",
    description: "Analytics server with limited access",
    serverUrl: "https://analytics.example.com/mcp",
    activeTools: ["get_metrics", "generate_report"], // Only these tools
  });
  ```

  ### Using `with` for Tool Selection

  While `activeTools` in `mcpTool` limits which tools are available from the server, you can further refine tool access at the sub agent level using `mcpTool.with`. This allows different agents to use different subsets of tools from the same MCP server.

  ```typescript
  import { agent, mcpTool } from "@inkeep/agents-sdk";

  // Define the MCP server with all available tools
  const customerSupportTool = mcpTool({
    id: "customer-support-tool",
    name: "Customer Support Tool",
    description: "Customer Support Tool",
    serverUrl: "https://customer-support.example.com/mcp",
  });

  // Agent that only uses specific tools from the server
  const customerSupportAgent = subAgent({
    id: "customer-support-agent",
    name: "Customer Support Agent",
    description: "Responsible for customer support",
    prompt: "You are a helpful assistant",
    canUse: () => [customerSupportTool.with({
        selectedTools: ["customer-support-tool"],
        headers: { "X-Custom-Header": "custom-value" }
      })],
  });
  ```
</SkillRule>

<SkillRule id="mcp-environment-aware" skills="typescript-sdk" title="Environment-Aware MCP Servers" description="Configure MCP tools to switch based on environment (dev vs production)">
  ## Environment-Aware MCP Servers

  You can also configure MCP tools to switch based on your environment. This is useful when you want to use different MCP tool configurations for development vs production.

  Creating environment-aware MCP tools is a two step process:

  ### Step 1: Define environment configurations

  <Tabs>
    <Tab title="Development Config">
      ```typescript title="projects/my-project/environments/development.env.ts"
      import { registerEnvironmentSettings, mcpTool } from '@inkeep/agents-sdk';
      import { CredentialStoreType } from '@inkeep/agents-core';

      export const development = registerEnvironmentSettings({
      mcpServers: {
      'customer_support_tool': mcpTool({
        id: 'customer-support-tool',
        name: 'Customer Support Tool',
        description: 'Customer Support Tool for development',
        serverUrl: 'http://localhost:3000/customer-support/mcp',
      })
      },
      });
      ```
    </Tab>

    <Tab title="Production Config">
      ```typescript title="projects/my-project/environments/production.env.ts"
      import { registerEnvironmentSettings, mcpTool } from '@inkeep/agents-sdk';
      import { CredentialStoreType } from '@inkeep/agents-core';

      export const production = registerEnvironmentSettings({
      mcpServers: {
      'customer_support_tool': mcpTool({
        id: 'customer-support-tool',
        name: 'Customer Support Tool',
        description: 'Customer Support Tool for production',
        serverUrl: 'https://customer-support.example.com/mcp',
      })
      },
      });
      ```
    </Tab>

    <Tab title="Index File">
      ```typescript title="projects/my-project/environments/index.ts"
      import { createEnvironmentSettings } from '@inkeep/agents-sdk';
      import { development } from './development.env';
      import { production } from './production.env';

      export const envSettings = createEnvironmentSettings({
      development,
      production,
      });
      ```
    </Tab>
  </Tabs>

  ### Step 2: Use the MCP tool in your sub agent

  ```typescript title="projects/my-project/agents/customer-support-agent.ts"
  import { subAgent } from "@inkeep/agents-sdk";
  import { envSettings } from "../environments";

  const customerSupportAgent = subAgent({
    id: "customer-support-agent",
    name: "Customer Support Agent",
    description: "Responsible for customer support",
    prompt: "You are a helpful assistant",
    canUse: () => [envSettings.getEnvironmentMcp('customer_support_tool')],
  });
  ```

  This pattern is useful if you want to keep track of different credentials for different environments. When you push your project using the [Inkeep CLI](/typescript-sdk/cli-reference#inkeep-push) `inkeep push` command with the `--env` flag, the credentials will be loaded from the appropriate environment file. For example, if you run `inkeep push --env development`, the credentials will be loaded from the `environments/development.env.ts` file.

  ### CLI Environment Variables

  The CLI respects these environment variables when using the `--env` flag:

  ```bash
  # Set environment name via environment variable
  export INKEEP_ENV=production
  inkeep push  # Uses production environment automatically

  # Override via CLI (takes precedence)
  inkeep push --env development  # Uses development instead
  ```
</SkillRule>