Skip to content
AIWCORPOMCP Platform

Build and register your first server

You need JDK 25, Linux or macOS (Windows only through WSL2) and a checkout of mcp-server-template. The platform artifacts come from Maven Central, so no registry login is needed.

Create the server

Section titled “Create the server”

  1. Pick a system id: 2 to 31 lower case letters and digits, not one the contracts reserve (gateway, broker, portal, admin and others). The examples use notes.

  2. Build the template once. The generator reads the id pattern from the contracts jar:

    Terminal window
    export JAVA_HOME="$(/usr/libexec/java_home -v 25)"   # macOS; on Linux the JDK 25 directory
    ./mvnw -B verify

  3. Generate the server:

    Terminal window
    ./new-server.sh notes

    This creates ../mcp-server-notes. Use ./new-server.sh notes /path/to/dir to put it elsewhere; the target must not exist and must lie outside the template.

  4. Build the new server:

    Terminal window
    cd ../mcp-server-notes
    git init
    ./mvnw -B verify

    The generated server builds and passes its tests without changes. The build also writes mcp-app/target/mcp-manifest.json.

Run it and read the manifest

Section titled “Run it and read the manifest”

  1. Start the jar in the dev profile. This profile serves plain HTTP on 127.0.0.1:8080 and accepts test keys, so run it only on your workstation, never in a container:

    Terminal window
    SPRING_PROFILES_ACTIVE=dev java -jar mcp-app/target/mcp-notes.jar

  2. Fetch the manifest. The path needs no token:

    Terminal window
    curl -s http://127.0.0.1:8080/.well-known/mcp-manifest

    Expected: a JSON document with serverId mcp-notes, system notes, the credential block, resourceTypes, policies, policiesHash and a tools list. Until the manifest is built the server answers 503.

  3. Check that every other path is closed:

    Terminal window
    curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8080/mcp \
      -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

    Expected: 401. Only a request with the gateway’s internal JWT gets through, see Authentication.

To call a tool without a platform, start LocalGateway in front of the server. The steps are in Write a server from the template.

Run it for the platform

Section titled “Run it for the platform”

  1. Fill in the three values in deploy/server.env:

    Terminal window
    MCP_GATEWAY_JWKS_URI=https://<platform>/.well-known/mcp-jwks.json
    MCP_CONNECT_URL=https://<platform>/connections?system={system}
    MCP_NOTES_URL=https://<system host>

  2. Build the image and start it. A generated server has no published image yet, so build:

    Terminal window
    cd deploy
    docker compose build
    docker compose up -d

  3. Read the certificate fingerprint:

    Terminal window
    docker compose logs mcp-notes | grep event=tls_certificate

    Expected: event=tls_certificate source=generated fingerprint=sha256:...

  4. Check the health path:

    Terminal window
    curl -fsSk https://localhost:8443/actuator/health

    Expected: {"status":"UP"...}.

The platform must reach this host on port 8443, and this host must reach https://<platform> on port 443.

Register it in the portal

Section titled “Register it in the portal”

Registration is done by a platform administrator in the portal. Give them the address https://<this host>:8443/mcp and the fingerprint from step 10.

  1. Ask the administrator to add the system notes and the server on the Servers page (the system first, see Systems).
  2. Ask them to compare the fingerprint with the one the portal shows, then approve the connection, the policies and each tool. Until all three are approved the tools answer tool_disabled.

Nothing in the platform restarts or changes configuration.