Connecting MCP Clients to Your Server

This guide shows how to connect MCP client applications, such as AI coding assistants, to a server that uses the HTTP transport.

This page is about connecting client applications to your server. For the server-initiated client features, such as sampling, elicitation, and roots, see Client Integration.

The only prerequisite is a running server that uses the HTTP transport. See Getting Started with HTTP Transport to create one.

What Every Client Needs

To connect to your server, a client needs three things:

  • The full endpoint URL, including the path, for example http://localhost:8080/mcp.

  • The transport type, which is Streamable HTTP. Point clients at /mcp, not /mcp/sse, unless the client only supports the legacy SSE protocol.

  • Network access to the server.

A localhost URL works out of the box while you develop. Connecting by hostname or IP address, or through a proxy, engages the origin check described in DNS Rebinding Protection, and a production server also needs authentication and TLS (see Security Reference).

Claude Code

Add the server with the Claude Code CLI:

claude mcp add --transport http greeting-server http://localhost:8080/mcp

Verify that it was added with claude mcp list. You can also define the server in a project-scoped .mcp.json file so that it is shared with your team.

Other Clients

Most clients that are configured with JSON follow the same shape: a named entry with a type of http and the server URL.

{
  "mcpServers": {
    "greeting-server": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

The exact file name and location differ by client. Consult the MCP clients documentation and each client’s own documentation for the authoritative configuration format, because these formats change over time.

Remote Servers

To connect clients from other machines, bind the server to a reachable address by setting quarkus.http.host, enable authentication as described in Security Reference, and serve over HTTPS. If you place a reverse proxy in front of the server, see the origin-check note in Troubleshooting HTTP Connections.

When the Connection Fails

If a client cannot connect, start with Troubleshooting HTTP Connections. A 403 response that a client reports as "authentication required" is usually not an authentication problem.

See Also