MCP Server

The Aurea MCP server — connect an AI agent to Aurea's case-management tools via the Model Context Protocol Streamable HTTP transport.

Overview

apps/api exposes an MCP (Model Context Protocol) server named aurea-concierge at:

POST http://localhost:4000/mcp

The server uses the Streamable HTTP transport from the official MCP SDK (@modelcontextprotocol/sdk). Each POST creates a fresh server instance — the server is stateless at the transport level.

Connecting an MCP client

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "aurea-concierge": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4000/mcp"]
    }
  }
}

Restart Claude Desktop. The four Aurea tools will appear in the tool picker.

MCP Inspector

npx @modelcontextprotocol/inspector http://localhost:4000/mcp

SDK-based agent (Node / Bun)

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const client = new Client({ name: 'my-agent', version: '1.0.0' })
const transport = new StreamableHTTPClientTransport(new URL('http://localhost:4000/mcp'))
await client.connect(transport)

const result = await client.callTool({ name: 'listCases', arguments: {} })
console.log(result)

Available tools

The aurea-concierge server registers four tools:

`listCases`

List all active immigration and relocation cases managed by Aurea.

Arguments: none

Returns: JSON array of Case objects.

[
  {
    "id": "1",
    "clientName": "Fernanda Oliveira",
    "service": "US_VISA",
    "status": "DOCUMENTS_PENDING",
    "country": "BR",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
]

`getCaseStatus`

Get the current status and full details of a specific case.

Arguments:

Prop

Type

Returns: a single Case object, or an error if the ID is not found.

{
  "id": "3",
  "clientName": "Catalina Herrera",
  "service": "CITIZENSHIP_APPLICATION",
  "status": "IN_REVIEW",
  "country": "CO",
  "createdAt": "2025-03-20T14:15:00.000Z"
}

`listServices`

List all immigration and relocation services offered by Aurea.

Arguments: none

Returns: JSON array of { id, label } objects.

[
  { "id": "US_VISA", "label": "US Visa Application" },
  { "id": "DIGITAL_NOMAD_VISA", "label": "Digital Nomad Visa" },
  { "id": "CITIZENSHIP_APPLICATION", "label": "Citizenship Application" },
  { "id": "SPANISH_DRIVERS_LICENSE", "label": "Spanish Driver's License Exchange" }
]

`advanceCaseStatus`

Advance a case to its next lifecycle status.

This tool mutates data. The confirm: true argument is required — the agent must obtain explicit user approval before calling this tool.

Arguments:

Prop

Type

Returns: the updated Case object with the new status.

Status progression:

INTAKE → DOCUMENTS_PENDING → SUBMITTED → IN_REVIEW → APPROVED

APPROVED and REJECTED are terminal — the tool is a no-op on those cases.

Authentication

The /mcp endpoint is currently open (no auth) for development convenience.

Do not expose POST /mcp to the public internet without adding authentication. The McpController has a TODO comment to add a Clerk JWT guard before production.

Server metadata

{ "name": "aurea-concierge", "version": "1.0.0" }

MCP Server

On this page