AdminConsole
Quickstarts/MCP
MCPLocal Reference15 minutes

Connect a read-only Mappls agent

a grounded documentation query through local stdio or authenticated stateless HTTP

Local Reference

What this path can prove

The MCP implementation is maintained in this repository and protocol-tested over stdio and Streamable HTTP. Live tool success still depends on the issued account, operation, region, and credential scope; production OAuth authorization-server registration, consent, lifecycle, and revocation remain company integrations.

Credential boundary

Keep provider credentials in the MCP server process or approved secret provider, never model context or client configuration committed to source. A remote internal gateway bearer or issuer-bound OAuth access token is independent from every Mappls provider credential. Documentation and migration tools require no live credential.

Provider-specific implementation intentionally stops here.

No public guide proves this distribution. Obtain the named entitled/private contract, attach its version and fingerprint to the project, then implement only inside the scaffolded adapter.

Before the timer starts

Prepare the exact environment

Do not count account, package, build-host, or device discovery as hidden quickstart work.

  1. 01

    Node.js 22 or newer

  2. 02

    An MCP-capable client or the downloadable Spatial Operations Agent

  3. 03

    A built `@mappls/mcp-server` package

  4. 04

    No credential for offline discovery; separately scoped non-production credentials only for approved live reads

Five-stage path

Build one complete result

Each stage has a proof. If the proof is missing, do not advance by assumption.

  1. 01

    Confirm the source line

    Open the linked evidence and confirm the exact MCP package, endpoint, toolchain, region, and account entitlement before installing anything. The MCP implementation is maintained in this repository and protocol-tested over stdio and Streamable HTTP. Live tool success still depends on the issued account, operation, region, and credential scope; production OAuth authorization-server registration, consent, lifecycle, and revocation remain company integrations.

  2. 02

    Create a clean boundary

    Build the server; start the Spatial Operations Agent in fixture mode or register its absolute local stdio entrypoint or exact authenticated HTTPS Streamable HTTP resource; keep the default remote profile offline; choose the controlled static-bearer hop or OAuth JWT resource-server mode; keep gateway and provider credentials separate; and grant no state-changing Mappls operation.

  3. 03

    Build one useful result

    Run the sample's solution_research journey across any of sixteen industries and thirteen target platforms, generate the portable integration manifest, then call the product-platform capability matrix, capability qualification planner, and live-conformance planner, documentation search, generation comparison, documentation coverage, and the exact stateful journey workshop before proposing integration code.

  4. 04

    Run the release path

    Run both server protocol suites and the fifteen-test agent suite; prove the default remote endpoint lists only 32 credential-free tools and rejects a hidden live call; execute one real stdio offline solution plan and integration manifest; retrieve one exact product-platform decision, its six-phase qualification journey, a bounded live-conformance plan, and an eight-lab journey workshop; prove exact generation differences and coverage gaps remain visible and ambiguous authentication choices remain selection-required; validate protected-resource discovery plus wrong-audience/expired/insufficient-scope tokens; reject unauthorized, wrong-origin, unsafe URL, oversized-body/output, missing-provenance, and token-reflection paths; and verify credential-shaped failures are redacted.

  5. 05

    Break it deliberately

    Exercise missing/denied credentials, unavailable network or runtime, invalid input, cancellation, and cleanup. Show a bounded user-safe failure while retaining a correlation identity for support.

Clean-path commands

Run what will ship

Replace documented placeholders through your environment or secret provider. Commands are scaffolds; platform signing, accounts, packages, and schemes remain project-specific.

$ npm run build --workspace @mappls/mcp-server

$ npm run test --workspace @mappls/mcp-server

$ node packages/mcp-server/dist/index.js

$ MAPPLS_MCP_HTTP_BEARER_TOKEN=YOUR_INDEPENDENT_32_BYTE_SECRET npm run start:http --workspace @mappls/mcp-server
Application-owned seam

Start with code you can replace

The scaffold keeps provider-specific symbols and credentials behind a narrow boundary. Bind the confirmed Mappls source line inside that adapter.

MCP first-success scaffold
{
  "mcpServers": {
    "mappls": {
      "command": "node",
      "args": ["/absolute/path/packages/mcp-server/dist/index.js"],
      "env": {
        "MAPPLS_STATIC_KEY": "${MAPPLS_STATIC_KEY}",
        "MAPPLS_INTOUCH_ACCESS_TOKEN": "${MAPPLS_INTOUCH_ACCESS_TOKEN}"
      }
    }
  }
}
Definition of first success

Verify behavior, not screenshots

  1. 1

    Fixture, real stdio, and remote HTTP share one governed application client contract. Local stdio and an explicit live-read deployment advertise 42 typed tools; default remote HTTP advertises only the 32 credential-free tools. Both profiles retain 38 resources and two prompts, OAuth mode binds an attributable principal/client/scope to the exact resource, remote HTTP retains no session registry, and no profile exposes writes.

  2. 2

    A blocked, missing, or unentitled provider produces a useful explicit failure rather than a blank surface or fabricated result.

  3. 3

    No server credential, bearer value, precise private fixture, or provider response body appears in client bundles, logs, screenshots, or test artifacts.

  4. 4

    Resources, listeners, sessions, processes, or requests stop cleanly when the owning screen, request, or application ends.

Before productionTools have least authorityGateway/OAuth and provider credentials are independentIssuer, resource audience, principal, client, expiry, and profile scope are enforcedConsent, rate limiting, revocation, TLS, and egress are production-governedWrites require separate design/approvalResults preserve provenanceCalls are scoped, metered, redacted, and traceableTools expose the least authority needed
Fast diagnosis

When first contact fails

Keep the safe provider request identity, resolved package/runtime versions, platform logs, and exact reproduction steps. Never attach credentials or private location payloads.

SignalLikely causeNext action
The client starts but lists no tools/resources, or a planned tool is unavailable

The package was not built, the stdio path/runtime or remote URL/auth is wrong, the configured profile is offline while the plan needs live-read, JWT issuer/audience/scope is mismatched, stdout contains non-protocol output, or a host/origin allowlist rejected the client.

Run the package build and protocol test directly, use solution_research and mappls_get_authentication_path to prove offline negotiation and credential placement, check credential-free health and protected-resource metadata, inspect only safe token classification, verify the absolute local entrypoint or exact HTTPS resource identity, then reconnect with the smallest profile.

Authentication or entitlement is rejected

The credential class, restriction, account region, host/path generation, package application, or subscribed capability does not match.

Do not try another credential shape blindly. Capture the safe status/request identity and reconcile the exact contract in the developer console or support packet.

The sample works once but not after reload, backgrounding, or a second run

Lifecycle ownership, listener disposal, token/session refresh, saved state, or a singleton initialization boundary is incomplete.

Instrument create/ready/cancel/destroy transitions and prove one owner before adding product behavior.

Keep building

From first success to a real journey

Choose the next tutorial only after the quickstart verification holds in your release path.