GoCanvas MCP Server (read-only)

A minimal Model Context Protocol server that exposes the read-only endpoints of the GoCanvas API v3 as MCP tools. Scope is limited to four areas: Forms, Submissions, Reports, and Reference Data. No create/update/delete operations are exposed.

Tools

Forms

Submissions

Reports

The three PDF tools return the binary PDF inline as base64 (content_base64, content_type, size_bytes) — the server is a pure passthrough and never writes to disk, so the tools work on read-only / ephemeral hosts such as AWS Lambda.

Reference Data

Authentication

refresh_oauth_token forces a fresh bearer token to be fetched and cached. It only applies to server-side OAuth (GOCANVAS_CLIENT_ID / GOCANVAS_CLIENT_SECRET) mode; in passthrough mode the caller owns the token and the server cannot refresh it. It is normally unnecessary — the server fetches a token on startup and refreshes it automatically before expiry and on a 401 — but it is exposed so the agent can rotate the token explicitly. The returned access token is masked.

Related MCP server: N-central MCP Server

Setup

This project uses uv. With uv installed, no manual environment setup is required — uv run resolves and installs dependencies (from pyproject.toml) automatically on first launch.

# optional: pre-create the environment
uv sync

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

The server is a thin passthrough to the GoCanvas API and starts with no credentials configured. Authentication is resolved per request, in the following priority order:

Other optional variables:

If no usable credentials are available for a call (no incoming Authorization header and no configured env credentials), the tool returns a clear error — the server itself still starts fine.

Running

Locally over stdio (default)

GOCANVAS_CLIENT_ID=... GOCANVAS_CLIENT_SECRET=... uv run server.py

Publicly over HTTP (e.g. Microsoft 365 Copilot custom agent, AWS Lambda)

Run with an HTTP transport and no GoCanvas credentials — the agent's OAuth bearer token is forwarded per request:

GOCANVAS_TRANSPORT=streamable-http GOCANVAS_HOST=0.0.0.0 GOCANVAS_PORT=8000 uv run server.py

The MCP endpoint is served at /mcp. Point your 365 Copilot custom agent's MCP connection at the public URL and configure its OAuth so it obtains a GoCanvas token; that token is passed through to the GoCanvas API on every tool call. No PDFs or other state are written to disk, so the server runs cleanly on read-only / ephemeral hosts.

Hosting publicly? Set GOCANVAS_ALLOWED_HOSTS to your public domain (or *). The default DNS-rebinding protection allows only localhost and returns HTTP 421 Misdirected Request for any other Host header.

On AWS Lambda

The module exposes an ASGI app (asgi_app()) and a Mangum-wrapped Lambda entry point (lambda_handler), so it runs on Lambda behind an API Gateway HTTP API or a Lambda Function URL with no long-running process. mangum is a declared dependency. Stateless + JSON-response mode is the default (Lambda containers are ephemeral and don't share session state, and API Gateway can't proxy an SSE stream).

A ready-to-deploy AWS SAM template is included (template.yaml); it provisions the function plus a public Function URL:

sam build
sam deploy --guided

The stack outputs the MCP endpoint (<FunctionUrl>/mcp). Point your agent there. Key details baked into the template:

• Handler: server.lambda_handler. Runtime: python3.12 (arm64).

• AuthType: NONE on the Function URL — required so the caller's Authorization bearer reaches the app for passthrough (AWS_IAM would consume it for SigV4). Auth is enforced at the app layer, not by Lambda.

• GOCANVAS_ALLOWED_HOSTS=* so the Function URL's own domain passes the rebinding check. Narrow it to your *.lambda-url.<region>.on.aws (or API Gateway) domain to tighten.

• For server-side OAuth instead of passthrough, set GOCANVAS_CLIENT_ID / GOCANVAS_CLIENT_SECRET in the function's environment (prefer Secrets Manager / SSM references over plaintext).

Payload-size limit. API Gateway / a buffered Function URL caps a response at 6 MB. The PDF tools return the file base64-encoded inline (~33% overhead), so a PDF larger than ~4.5 MB can exceed that limit. Raise MemorySize/Timeout for large forms; for consistently large PDFs, front the function with a Function URL in RESPONSE_STREAM invoke mode or fetch the PDF out-of-band.

MCP client configuration

Use uv run as the command. --directory points uv at this project so it uses the right dependencies regardless of the client's working directory:

{
  "mcpServers": {
    "gocanvas": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/GoCanvas",
        "server.py"
      ],
      "env": {
        "GOCANVAS_CLIENT_ID": "your_client_id",
        "GOCANVAS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

If uv isn't on the client's PATH, use its absolute path (e.g. ~/.local/bin/uv) as the command.

{
  "mcpServers": {
    "gocanvas": {
      "command": "/absolute/path/to/GoCanvas/.venv/bin/python",
      "args": ["/absolute/path/to/GoCanvas/server.py"],
      "env": {
        "GOCANVAS_CLIENT_ID": "your_client_id",
        "GOCANVAS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

On Windows the interpreter is at .venv\Scripts\python.exe. Using a bare python will fail with ModuleNotFoundError: httpx because the client does not use your activated shell environment.

Notes

• Pagination: list tools accept a page argument. Response pagination headers (link, current-page, page-items, total-count, total-pages) are surfaced under a pagination key in the tool result.

• Rate limiting: the server honors 429 Too Many Requests responses, waiting according to the RateLimit-Reset / RateLimit-Remaining headers (or a bounded exponential backoff) before retrying, per GoCanvas best practices.