Model Context Protocol Discovery & Initialization

Before any tool can be called, MCP clients go through discovery.

This is how a client learns:

• What tools exist
• What inputs they expect
• What outputs they return

You don't manually implement discovery — MCP does it automatically when the server starts.

What Happens During Discovery?

When an MCP client connects:

1. The server starts
2. MCP advertises:
   • Server name & version
   • List of tools
   • Input schemas for each tool
3. The client caches this information
4. Tools become callable

This is why schemas matter — discovery is schema-driven.

Initialization Happens When the Server Starts

This code is the initialization point:

const server = new McpServer({
  name: "My MCP Server",
  version: "1.0.0",
});

const transport = new StdioServerTransport();
server.connect(transport);

Once connect() is called:

• The server is live
• Discovery is enabled
• Tools can be listed by clients

Tool Registration Happens Before Discovery

Important rule:

Register all tools before calling connect()

Correct order ✅

const server = new McpServer({
  name: "My MCP Server",
  version: "1.0.0",
});

// register tools here
server.tool(...);
server.tool(...);

server.connect(new StdioServerTransport());

Wrong order ❌

server.connect(new StdioServerTransport());

// tools added too late
server.tool(...);

If tools are registered after connect, clients may not discover them.

Discovery Example (What the Client Sees)

From the client's perspective, discovery returns something like:

{
  "server": {
    "name": "My MCP Server",
    "version": "1.0.0"
  },
  "tools": [
    {
      "name": "getUser",
      "inputSchema": {
        "userId": "string"
      }
    }
  ]
}

You don't build this manually — MCP generates it from your tool definitions.

Why Discovery Is Critical for API Wrapping

When wrapping APIs:

• Discovery prevents the AI from guessing parameters
• Clients know exactly what inputs are allowed
• Output shapes stay consistent
• Tool misuse drops dramatically

This is the biggest difference between:

• ❌ "AI calling an API"
• ✅ "AI calling an MCP tool"

Want to understand how discovery works? Read our guide on MCP Discovery & Initialization.

Common Discovery Mistakes

• ❌ Registering tools dynamically after startup
• ❌ Changing schemas without bumping version
• ❌ Returning optional or unstable fields
• ❌ Using free-text outputs

Simple Rule to Remember

If a tool isn't discoverable, it doesn't exist.

Always think:

"Would a client understand this tool without reading my code?"

If yes → you did discovery right.

Ready to test your MCP server? Test it now on MCP Playground →