Hello AI World: MCP and API-first approach

Let's build a simple "Hello World" API using MCP and OpenAPI. Something that can be used as a starting point for your own projects. This example will demonstrate how to define, implement, and consume an API using the Model Context Protocol (MCP) and OpenAPI.

Choose Your Deployment

• Cloud:

  • Use the webapp dashboard to create and test endpoints.
  • No code required—just configure and deploy via UI.

• On-Premise:

  • Use the hapi CLI, to create and serve APIs.
  • Start with a simple OpenAPI schema and let the HAPI Server generate the endpoints.
  • Start HAPI Servers and configure DNS as needed.

1. Define the OpenAPI Schema

If you don't have a schema yet, define your OpenAPI schema for the "Hello World" API. This schema describes the API's endpoints, request parameters, and response formats.

# example.yaml
openapi: 3.1.0
info:
  title: Hello World API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Returns Hello World
      operationId: getHello
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

---

2. Greenfield vs Brownfield

The HAPI Server idea got born from the need to provide a flexible, API-first development experience that can adapt to various project needs. The HAPI Stack supports both greenfield and brownfield development, allowing you to either start fresh with a new project or integrate into an existing one.

Brownfield projects can leverage existing OpenAPI schemas and HAPI's dynamic endpoint generation to enhance their API capabilities without the need to code a single line.

• Greenfield:
  • Create a new project with the above OpenAPI schema.
  • Use HAPI server to auto-generate endpoints.
  • Deploy to the cloud or on-premise.
• Brownfield:
  • Integrate the schema into an existing project.
  • Ensure your server can handle the /hello endpoint.

On-Premise (manual steps)

🟩 Greenfield

1. Initialize a new HAPI project (only in greenfield projects):

# Check available API Specs
hapi list
# GREENFIELD: Create a new project with the OpenAPI schema
hapi init example

The parameter example is the name of your project (swagger file without the .yaml|json extension).

This command, init, creates a new project with the OpenAPI schema defined above, generating the necessary files and directories.

Start the example project:

hapi serve example --mcp

Implement the Endpoint

For greenfield projects, you must implement the /hello endpoint in your server code, the hapi init command generates a scaffold for you, but you must fill in the logic. Below the actual implementation auto-generated by HAPI:

  // #region functions for path /hello
    async getHello() {
      console.log('This is the get method for /hello')
      return {
        success: true, 
        path: '/hello', 
        method: 'GET',
        timestamp: new Date().toISOString()
      }
    },  
  // #endregion

The HAPI Server determine the request and response structure based on the OpenAPI schema you defined.

🟫 Brownfield

Integrate the schema into an existing project:

hapi serve example --headless

The parameter example is the name of your project (swagger file without the .yaml|json extension).

The --headless flag allows you to run the server without an API server implementation, instead it will consume the services defined in the OpenAPI schema. This is useful for brownfield projects where you want to leverage existing APIs without implementing them from scratch.

---

3. Test the API

Test the API (the "head" piece).

curl http://localhost:3000/hello
# { "success": true, "path": "/hello", "method": "GET", "timestamp": "2025-07-27T12:00:00Z" }

Test the MCP endpoint ("headless").

curl http://localhost:3000/mcp
# { "success": true, "path": "/hello", "method": "GET", "timestamp": "2025-07-27T12:00:00Z" }

Testing tools

For the APIs, you can use the built-in API explorer on-premise: http://localhost:3000/swagger; cloud users can access the API explorer via the runMCP dashboard or directly at http://[YOUR-SUBDOMAIN].run.mcp.com.ai/swagger. And of course, you can use any HTTP client like Postman, Insomnia, Scalar, or even your browser to test the endpoints.

For the MCP endpoints, you can use the chatMCP, MCP Inspector, Postman, or any other HTTP client that supports MCP, even curl. More details on how to use curl with MCP can be found in the MCP CLI documentation.

---

See this in action

Further Reading

• OpenAPI Specification