Skip to main content
Glama
Harborboard

Harborboard

by ali-dev5490

Harborboard

The Model Context Protocol lets an AI client call tools, read resources, and fetch prompts from a server you control. Harborboard is a Laravel app that exposes a real classifieds CRM — listings, leads, and orders — through that protocol.

It is a portfolio piece for MCP, AI integration, and SaaS work: a small domain with authorization, two transports, and tests, rather than a single hard-coded tool.

Package choice

This app uses laravel/mcp 1.2.1 (constraint ^1.2), the official Laravel package. It is stable, it requires Laravel 12.41.1 or 13, and the framework docs describe its tools, resources, prompts, stdio server, and streamable HTTP server. The app itself is Laravel 12.73 on PHP 8.3+ (developed and tested on 8.4).

mcp/sdk is the official framework-agnostic PHP SDK. It is still marked experimental before 1.0, so it is a better fit outside Laravel. php-mcp/server is unmaintained. Laravel MCP is the right dependency for this codebase.

HTTP authentication uses Laravel Sanctum personal access tokens. Laravel's MCP guide recommends Sanctum when the application does not already run Passport, and recommends Passport when a client can only authenticate with OAuth 2.1. Passport, including the discovery routes Laravel MCP registers, is listed on the roadmap below.

Related MCP server: GTM MCP Server

Architecture

flowchart LR
  subgraph clients [MCP clients]
    Claude[Claude Desktop]
    Cursor[Cursor]
    Inspector[MCP Inspector]
  end

  subgraph transports [Transports]
    Stdio["stdio\nphp artisan mcp:start harbor"]
    Http["Streamable HTTP\nPOST /mcp/harbor"]
  end

  subgraph app [Harborboard]
    Sanctum[Sanctum ability mcp:use]
    Limit[Rate limit]
    Server[HarborServer]
    Tools[Tools]
    Resources[Resources]
    Prompts[Prompts]
    DB[(Workspace database)]
  end

  Claude --> Stdio
  Cursor --> Stdio
  Inspector --> Stdio
  Inspector --> Http
  Http --> Sanctum --> Limit --> Server
  Stdio --> Server
  Server --> Tools --> DB
  Server --> Resources --> DB
  Server --> Prompts --> DB

routes/ai.php registers one server twice:

  • Mcp::local('harbor', HarborServer::class) starts as php artisan mcp:start harbor for Claude Desktop, Cursor, and MCP Inspector.

  • Mcp::web('/mcp/harbor', HarborServer::class) is the streamable HTTP endpoint. It requires auth:sanctum, a token ability of mcp:use (or *), and the mcp rate limiter (60 requests per minute by default).

The stdio process has no HTTP user. It acts as HARBOR_LOCAL_USER (the seeded owner). That fallback is refused for web requests and for the test suite.

What the domain contains

Northline Studio is a seeded workspace that sells furniture and lighting. Members share one workspace and have a role:

Role

Read

Create and update leads, place orders

Archive listings

Viewer

Yes

No

No

Agent

Yes

Yes

No

Owner

Yes

Yes

Yes

Write tools that a role cannot use are omitted from tools/list, so the model is not invited to call them. Policies still run inside the handler.

Seeded people (local fixtures, password password):

Email

Name

Role

owner@harborboard.test

Avery Chen

owner

agent@harborboard.test

Jordan Hale

agent

viewer@harborboard.test

Sam Okonkwo

viewer

Seeded catalog:

Slug

Status

Price

oak-writing-desk

published

840.00 USD

linen-lounge-chair

published

620.00 USD

brass-arc-lamp

published

310.00 USD

walnut-media-console

draft

1290.00 USD

ceramic-table-lamps

sold

180.00 USD

marble-side-table

archived

450.00 USD

Maya Ellis is a qualified lead on the oak desk. Chris Patel is a new lead on the lounge chair. Priya Shah already has fulfilled order HB-1-0001.

Tools

Prices in arguments are major currency units (700 means 700.00). Prices in results are decimal strings with a currency code.

Tool

Access

What it does

search-listings

read

Text, status, category, price range, sort, paging

get-listing

read

One listing by id or slug, with lead counts

search-leads

read

Text, status, listing, assignee

get-lead

read

One lead plus its activity history

pipeline-summary

read

Counts, money by order status, leads that need attention

search-orders

read

Orders, optionally by status

create-lead

agent, owner

Validates and writes immediately. An idempotency_key returns the original lead on retry

update-lead-status

agent, owner

Moves new, contacted, qualified, and lost. Repeating the same status is a no-op. converted is rejected

place-order

agent, owner

Preview unless confirm is true. A confirmed call creates the order, converts the lead, and marks the listing sold

archive-listing

owner

Preview unless confirm is true. The preview includes open leads. Archiving twice is safe

place-order and archive-listing are the confirmation gate. The first call, with confirm omitted or false, returns requires_confirmation: true and writes nothing. A second call with confirm: true commits. A model that guesses an order still has to pass that flag, and the host should show the preview to a person before it does.

Resources and prompts

Kind

Name

URI or arguments

Resource

workspace-overview

harbor://workspace/overview

Resource

qualification-playbook

harbor://playbook/qualification

Resource template

listing

harbor://listings/{listing}

Resource template

lead

harbor://leads/{lead}

Prompt

qualify-lead

lead_id, optional tone (direct, warm, concise)

Prompt

draft-follow-up

lead_id, optional channel (email, sms)

Prompt

weekly-pipeline-review

optional focus (listings, leads, orders, all)

Prompts embed the current database row. They do not send email or change statuses.

Quick start

Requirements: PHP 8.3 or 8.4 with mbstring, xml, curl, sqlite, zip, bcmath, and intl, plus Composer. Node is only required for MCP Inspector. The home page does not need a frontend build.

composer.json pins the Composer platform to PHP 8.3.27, so composer update keeps a lock file that installs on both 8.3 and 8.4. Symfony 8 requires PHP 8.4, and this app stays on the Symfony 7 line Laravel 12 also accepts.

git clone https://github.com/ali-dev5490/laravel_mcp.git
cd laravel_mcp
composer setup
php artisan serve

composer setup installs dependencies, copies .env.example to .env, generates APP_KEY, creates database/database.sqlite, and runs php artisan migrate --force --seed.

The same steps by hand:

composer install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate --seed
php artisan serve

Open http://127.0.0.1:8000. After seeding, the page shows Northline Studio's listing, lead, and order counts.

SQLite is the default. Point DB_* at MySQL or Postgres if you want another engine; the migrations use the Laravel schema builder.

Issue an HTTP token (shown once):

php artisan harbor:token owner@harborboard.test

Claude Desktop

Claude Desktop config lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Use the absolute path to artisan:

{
  "mcpServers": {
    "harborboard": {
      "command": "php",
      "args": [
        "/absolute/path/to/laravel_mcp/artisan",
        "mcp:start",
        "harbor"
      ]
    }
  }
}

Restart Claude Desktop. The server runs as HARBOR_LOCAL_USER from .env, which defaults to the seeded owner. Ask Claude to search published listings under $700.

Cursor

This repository includes .cursor/mcp.json. Cursor starts the server with the project as the working directory:

{
  "mcpServers": {
    "harborboard": {
      "command": "php",
      "args": ["artisan", "mcp:start", "harbor"]
    }
  }
}

For the HTTP transport, run php artisan serve, mint a token, and point Cursor at the URL:

{
  "mcpServers": {
    "harborboard-http": {
      "url": "http://127.0.0.1:8000/mcp/harbor",
      "headers": {
        "Authorization": "Bearer YOUR_SANCTUM_TOKEN"
      }
    }
  }
}

MCP Inspector

Stdio, which is the same command Claude and Cursor run:

php artisan mcp:inspector harbor

Or the Inspector CLI, which connects, lists or calls, and exits:

npx @modelcontextprotocol/inspector --cli php artisan mcp:start harbor --method tools/list
npx @modelcontextprotocol/inspector --cli php artisan mcp:start harbor \
  --method tools/call --tool-name search-listings \
  --tool-arg status=published --tool-arg max_price=700

HTTP, with the app already serving and a bearer token pasted into the Inspector's header field:

php artisan serve
php artisan mcp:inspector mcp/harbor

A verified stdio listing returns all ten tools. A verified call to search-listings with status=published and max_price=700 returns the brass arc lamp (310.00) and the linen lounge chair (620.00), and leaves the oak desk out.

Example conversation

You: Which published pieces are under $700, and who still needs a first reply?

The client calls search-listings and search-leads. It should name the brass arc lamp and the linen lounge chair, and it should name Chris Patel as a new lead. The oak desk is 840.00, so it stays out of the price filter. Maya Ellis is already qualified, so she is not waiting on a first reply.

You: Draft a short SMS to Chris about the lounge chair. Then preview an order for Maya's desk. Do not place it.

The client calls draft-follow-up with Chris's lead id and channel=sms, then place-order with Maya's lead id and confirm false. The preview looks like this and the database is unchanged:

{
  "committed": false,
  "requires_confirmation": true,
  "message": "No order was written. Show this preview to the user, then call place-order again with confirm=true to commit it.",
  "preview": {
    "buyer": "Maya Ellis",
    "listing": "Oak writing desk",
    "amount": "840.00",
    "currency": "USD",
    "resulting_lead_status": "converted",
    "resulting_listing_status": "sold"
  },
  "order": null
}

You: Place it.

Only then should the client call place-order with confirm true. The lead becomes converted, the listing becomes sold, and a second confirmed call is rejected because the order already exists.

You: Read the qualification playbook and tell me whether Elena Rossi is ready to buy the brass lamp.

The client reads harbor://playbook/qualification and get-lead. Elena is contacted, which is not qualified, so the answer should be to ask the remaining question rather than to preview an order.

Security

  • Every query is filtered by the signed-in member's workspace_id. A miss is reported as not in the caller's workspace, so another tenant's ids are not confirmed.

  • Viewers do not receive write tools. Agents do not receive archive-listing. Policies repeat those checks inside the handlers.

  • place-order and archive-listing write only when confirm is true. Show that preview to a person. The flag is a server-side gate, and a careful host still asks the user before setting it.

  • create-lead accepts an idempotency_key. The same key returns the original lead and ignores the second payload.

  • HTTP tokens need the mcp:use ability. php artisan harbor:token prints the plain token once; Sanctum stores only its hash.

  • The mcp limiter allows HARBOR_MCP_RATE_LIMIT requests per minute (default 60), keyed by user id.

  • Laravel MCP checks the Origin header on web requests and rejects origins other than the app URL and localhost.

  • The stdio server trusts the operating-system user and acts as HARBOR_LOCAL_USER. Bind that address to a real member, and keep mcp:start on the machine that owns the data.

  • The seeded password is a local fixture. Change it, or skip the seeder, before any shared deployment. .env.example contains no credentials beyond that published demo password.

Tests and CI

Pest covers the tool catalog by role, search scoping, validation, idempotency, the lead state machine, order preview versus commit, resources, prompts, Sanctum, the token ability, rate limiting, and the token command. Pint and Larastan (PHPStan level 6) run locally and in CI.

vendor/bin/pint
vendor/bin/phpstan analyse
php artisan test

GitHub Actions (.github/workflows/ci.yml) runs those three on PHP 8.3 and 8.4 for every push and pull request.

Docker

Docker is optional. SQLite and composer setup are enough for local use.

docker compose up --build

The container listens on port 8000, installs Composer dependencies when vendor/ is missing, generates APP_KEY when it is empty, and migrates and seeds. Re-running the seeder is a no-op once the northline workspace exists. Reset with php artisan migrate:fresh --seed.

Project layout

app/Mcp/Servers/HarborServer.php      Server name, instructions, registration
app/Mcp/Tools                         Ten tools
app/Mcp/Resources                     Static resources and URI templates
app/Mcp/Prompts                       Qualify, follow-up, weekly review
app/Domain                            Status machine, orders, pipeline
app/Policies                          Workspace and role checks
routes/ai.php                         stdio handle and HTTP route
config/harbor.php                     Local user, demo accounts, rate limit

Roadmap

  • OAuth 2.1 with Laravel Passport and Mcp::oauthRoutes(), for clients that cannot hold a token you mint yourself

  • Cancel and refund an order without leaving the listing sold

  • A Livewire desk on top of the same models, so the workspace is usable without an MCP client

  • Listing photos as blob resources

  • A signed webhook when an order is placed

License

MIT. See LICENSE.

Hire me

Built as a portfolio piece by a senior Laravel engineer (9+ years) who ships Laravel, Vue, and Livewire products and wires them to OpenAI and MCP clients.

  • Name: [Your name]

  • Upwork: [Your Upwork profile URL]

  • Email: [you@example.com]

  • GitHub: [your GitHub URL]

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      F
      maintenance
      Enables AI assistants to manage RogerRoger CRM data including people, organizations, lists, tags, and tasks through standardized MCP tools.
      22
      8 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to perform go-to-market workflows such as company and contact enrichment, CRM querying, and controlled, audited writes to a CRM through MCP tools callable from any MCP client.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible AI clients to search and view CRM customers, deals, contracts, tasks, calendars, and outbound jobs, and to propose opt-in write actions that require human approval in the CRM.
      Apache 2.0