Skip to main content
Glama
MCP Connect Starter

MCP Connect Starter

by cdtalley

MCP Connect Starter

CI License: MIT Python 3.10+

A clean, runnable, production-minded starter for building an MCP server that connects Claude, Cursor, or ChatGPT to your own tools -- with the security patterns (read-only enforcement, least-privilege scopes, PII redaction, audit logging) you actually want before you put one in front of real company data.

The Model Context Protocol (MCP), in two sentences: MCP is an open, JSON-RPC-based protocol that lets an AI assistant discover and call a server's tools (and read its resources) over a standard transport -- stdio for local processes, or HTTP for remote ones -- instead of every assistant and every backend needing a bespoke integration. This repo is a server: it exposes tools, the assistant (Claude Desktop, Cursor, ChatGPT, ...) is the client that calls them.

Everything below runs with zero external accounts: a bundled SQLite demo database, a bundled markdown knowledge base, and a bundled mock CRM/ticketing fixture. Clone it, run it, and read the code to see the patterns -- then swap in your own data and real systems.


Architecture

flowchart LR
    subgraph Clients
        A[Claude Desktop]
        B[Cursor]
        C["ChatGPT (remote connector)"]
    end

    subgraph Server["MCP Connect Starter"]
        T["Transport: stdio or streamable HTTP"]
        S["security.py<br/>scopes/allowlist &middot; audit log &middot; PII redaction"]
        SQL["sql_connector<br/>(read-only)"]
        DOCS["docs_connector"]
        CRM["crm.MockCRMAdapter<br/>(swap via crm.CRMAdapter)"]
    end

    DB[("demo.sqlite3<br/>customers / orders / deals")]
    MD[("data/docs/*.md")]
    JSON[("crm_mock.json")]
    REAL["Your real systems:<br/>HubSpot &middot; Salesforce &middot; Jira &middot; Drive"]

    A -- stdio --> T
    B -- stdio --> T
    C -- streamable HTTP --> T
    T --> S
    S --> SQL --> DB
    S --> DOCS --> MD
    S --> CRM --> JSON
    CRM -. implement CRMAdapter .-> REAL

Every tool call flows through security.secure_tool: it checks the caller-independent, server-side scope/allowlist policy, runs the connector, redacts PII from the result, and writes a structured audit log line -- regardless of whether the call succeeded, was denied, or errored.

Related MCP server: Governed MCP Gateway

Quickstart

Requires Python 3.10+.

git clone <this-repo-url> mcp-connect-starter
cd mcp-connect-starter

# pip
pip install -e ".[dev]"
# ...or uv
uv pip install -e ".[dev]"

# Run the test suite
pytest

# Lint
ruff check .

# Run over stdio (what Claude Desktop / Cursor launch for you)
mcp-connect-starter --transport stdio

# Run over streamable HTTP (for remote use / ChatGPT connectors)
mcp-connect-starter --transport http --host 0.0.0.0 --port 8080
# -> http://0.0.0.0:8080/mcp  (health check: http://0.0.0.0:8080/healthz)

The demo SQLite database is created automatically on first run (see src/mcp_connect_starter/seed_data.py); there's nothing to provision.

Docker

docker compose up --build
# MCP endpoint:   http://localhost:8080/mcp
# Health check:   http://localhost:8080/healthz

Connecting a client

These are the connection methods that exist today for each client. Check that client's current docs if something here looks out of date -- this space moves fast.

Claude Desktop

Add to your claude_desktop_config.json (Settings -> Developer -> Edit Config):

{
  "mcpServers": {
    "mcp-connect-starter": {
      "command": "mcp-connect-starter",
      "args": ["--transport", "stdio"]
    }
  }
}

If mcp-connect-starter isn't on the PATH Claude Desktop sees, use an absolute interpreter path instead, e.g. "command": "/path/to/venv/bin/mcp-connect-starter".

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "mcp-connect-starter": {
      "command": "mcp-connect-starter",
      "args": ["--transport", "stdio"]
    }
  }
}

Or, pointed at a server you're already running over HTTP:

{
  "mcpServers": {
    "mcp-connect-starter": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

ChatGPT

ChatGPT's connectors (Settings -> Connectors, on plans that support custom connectors) call a remote MCP server over HTTP -- there is no stdio option for ChatGPT. Run this server with --transport http somewhere reachable (your own deployment, or a tunnel like ngrok/cloudflared for local testing) and register https://your-host/mcp as the connector's server URL.

Example prompts

These are real tool outputs from the bundled demo data (SQLite customers/orders/deals, the markdown docs, and the mock CRM), lightly trimmed. Your assistant decides which tool(s) to call based on the prompt; this is what comes back.

"Which companies have the most closed-won deal value?" -> sql_query

{
  "columns": ["company", "total_value"],
  "rows": [
    {"company": "Northfjord Analytics", "total_value": 390000.0},
    {"company": "Fernhollow Foods", "total_value": 95000.0},
    {"company": "Cobalt Reef Robotics", "total_value": 9600.0}
  ],
  "row_count": 3,
  "truncated": false
}

"What's our refund policy?" -> search_docs then read_doc

{
  "result": [
    {
      "path": "refund-policy.md",
      "title": "Refund Policy",
      "score": 10,
      "snippet": "# Refund Policy _Last updated: 2024-01-02_ This is sample knowledge-base content bundled with the MCP Connect starter, used to demonstrate t..."
    }
  ]
}

"Show me our open support tickets." -> list_tickets

{
  "result": [
    {
      "id": "TCK-2005",
      "subject": "Robotics telemetry connector dropping packets",
      "status": "open",
      "priority": "P1",
      "requester_email": "[REDACTED_EMAIL]",
      "assignee": "Support: Alex Chen",
      "created_at": "2024-01-10T06:22:00Z",
      "updated_at": "2024-01-10T07:05:00Z",
      "description": "~3% of telemetry packets from the robotics fleet connector are being dropped since last night's deploy.",
      "comments": []
    }
  ]
}

Note the requester's email came back redacted -- that's the PII filter running on every tool call, not something the prompt asked for.

"Delete the customers table." -> sql_query is called, and rejected before it ever reaches SQLite:

Error executing tool sql_query: Only SELECT (or WITH ... SELECT) statements are allowed.

Security model

This is the part worth reading before you point this at anything real.

Read-only SQL, enforced twice. security.ensure_read_only_sql rejects anything that isn't a single SELECT / WITH ... SELECT statement -- no INSERT/UPDATE/DELETE, no DDL, no multi-statement payloads, comments stripped first so a write can't hide behind -- or /* */. Independently, the SQLite connection itself is opened via a read-only URI (mode=ro) with PRAGMA query_only = ON, so a write fails even if the text-based guard were somehow bypassed. Queries use ? placeholders with bound params -- never string-formatted values -- and results are capped at MCP_CONNECT_SQL_MAX_ROWS rows (default 200), with a progress-handler based timeout bounding how long a single query may run.

Least privilege, per tool. Every tool declares the scope(s) it needs (config/scopes.yaml). A tool only runs if the server was explicitly granted every scope it requires (MCP_CONNECT_GRANTED_SCOPES), and enabled: false in that file turns a tool off outright regardless of scopes. The one write-capable tool in the starter, add_ticket_comment, requires crm:write and ships disabled by default -- the server is read-only out of the box, on purpose. An optional hard allowlist (MCP_CONNECT_ALLOWED_TOOLS) can further restrict which tool names are exposed at all, independent of scopes.

PII redaction on every tool output. redaction.py pattern-matches emails, phone numbers, SSNs, Luhn-validated card numbers, AWS access keys, and key=value-style secrets, replacing each with a [REDACTED_<KIND>] tag. It runs twice: once at the connector (e.g. the SQL connector redacts rows right after fetching them) and once generically on every tool's return value in security.secure_tool -- including inside nested dicts, lists, and Pydantic models -- so a connector that forgets to redact doesn't leak anything.

Structured audit logging of every call. Every tool invocation -- allowed, denied, or errored -- emits one JSON line via audit.py: a request id, the tool name, status, duration, the scopes required vs. granted, and the names (never values) of the arguments passed. These always go to stderr, never stdout, because stdout carries the JSON-RPC wire format on the stdio transport and must stay uncontaminated. Set MCP_CONNECT_AUDIT_LOG_FILE to also append them to a file for shipping to a log pipeline.

Secrets via environment variables only. Every configurable value (config.py) is read from an environment variable with a working default; nothing secret is ever hard-coded or committed. .env.example documents every variable, including the pattern for a real connector's credentials (e.g. HUBSPOT_API_KEY) that the bundled mock adapter doesn't use but a real one would.

Repository layout

src/mcp_connect_starter/
  server.py              # builds the FastMCP app, registers every tool
  cli.py                 # `mcp-connect-starter` entry point (stdio | http)
  config.py              # all env-driven configuration in one place
  security.py            # scopes/allowlist enforcement + the SQL guard
  redaction.py           # PII pattern matching
  audit.py               # structured JSON audit logging
  seed_data.py           # builds the bundled demo SQLite database
  connectors/
    sql_connector.py     # read-only SQL over the demo database
    docs_connector.py    # markdown knowledge-base search/read
    crm/
      base.py            # CRMAdapter interface + Ticket/Contact models
      mock_adapter.py    # zero-account mock, backed by crm_mock.json
data/
  docs/*.md              # bundled knowledge base
  crm_mock.json          # bundled mock CRM/ticketing fixture
config/
  scopes.yaml            # least-privilege tool policy
tests/                   # pytest: redaction, read-only guard, tool behavior

How to add your own connector

  1. Write the connector. Create connectors/your_connector.py with a plain function (sync or async) that takes typed arguments and returns a Pydantic model (or a list of them) -- that gives you a real JSON schema on the wire for free. Redact PII at the source if your data is likely to contain any; the generic filter in security.secure_tool is a backstop, not a replacement.

  2. Register it as a tool in server.py:

    @mcp.tool()
    @secure_tool("your_tool_name", scopes=["your_scope:read"])
    def your_tool_name(arg: str) -> YourResultModel:
        """One sentence the assistant will read to decide when to call this."""
        return your_connector.do_the_thing(arg)
  3. Add it to config/scopes.yaml with the scope(s) it needs (and enabled: true/false). If you skip this, the tool defaults to enabled and requires exactly the scopes you passed to secure_tool.

  4. Write a test in tests/test_your_connector.py covering at least one success case and one failure/edge case (empty input, not-found id, a write attempt if relevant).

Swapping in a real CRM/ticketing system

connectors/crm/base.py defines CRMAdapter: list_tickets, get_ticket, search_contacts, add_ticket_comment. The bundled MockCRMAdapter implements it against a JSON fixture. To connect HubSpot, Salesforce, Jira, Zendesk, or a Google Drive-backed sheet:

# connectors/crm/hubspot_adapter.py
import os
import httpx
from .base import CRMAdapter, Contact, Ticket

class HubSpotAdapter(CRMAdapter):
    def __init__(self):
        self._api_key = os.environ["HUBSPOT_API_KEY"]  # env var only, never committed

    def get_ticket(self, ticket_id: str) -> Ticket:
        resp = httpx.get(
            f"https://api.hubapi.com/crm/v3/objects/tickets/{ticket_id}",
            headers={"Authorization": f"Bearer {self._api_key}"},
        )
        if resp.status_code == 404:
            raise LookupError(f"No such ticket: '{ticket_id}'.")
        resp.raise_for_status()
        return Ticket.model_validate(_map_hubspot_ticket(resp.json()))
    # ... list_tickets, search_contacts, add_ticket_comment ...

Then change one line in server.py's _build_crm_adapter():

def _build_crm_adapter() -> CRMAdapter:
    return HubSpotAdapter()  # was: MockCRMAdapter(config.CRM_FIXTURE_PATH)

Nothing else changes -- every tool already talks to the adapter only through the CRMAdapter interface. The same pattern applies to Salesforce, Jira, or a Google Drive-backed connector: implement the interface your connector needs (or add a new one next to CRMAdapter if the shape is different enough, e.g. a DocsAdapter for a live Drive/Confluence sync instead of docs_connector's local-folder scan), read credentials from environment variables, and swap the construction site.

Testing & CI

pytest          # redaction, read-only SQL guard, and tool behavior
ruff check .     # lint

GitHub Actions (.github/workflows/ci.yml) runs both on every push and pull request, across Python 3.10-3.12.

Configuration reference

See .env.example for the full list; the highlights:

Variable

Default

Purpose

MCP_CONNECT_DB_PATH

./data/demo.sqlite3

SQLite database path

MCP_CONNECT_DOCS_DIR

./data/docs

Knowledge-base folder

MCP_CONNECT_CRM_FIXTURE

./data/crm_mock.json

Mock CRM fixture

MCP_CONNECT_SQL_MAX_ROWS

200

Max rows per SQL query

MCP_CONNECT_SQL_TIMEOUT_S

5

Per-query timeout (seconds)

MCP_CONNECT_GRANTED_SCOPES

data:read,docs:read,crm:read

Scopes this deployment holds

MCP_CONNECT_ALLOWED_TOOLS

(unset = all)

Optional hard tool-name allowlist

MCP_CONNECT_SCOPES_FILE

./config/scopes.yaml

Tool policy file

MCP_CONNECT_AUDIT_LOG_FILE

(unset = stderr only)

Also append audit JSON lines here

MCP_CONNECT_HTTP_HOST / _PORT

127.0.0.1 / 8080

Streamable HTTP bind address

License

MIT -- see LICENSE.


Want this wired into your stack?

This repo is the open-source starting point. Prismbase MCP Connect is a fixed-price service that takes it the rest of the way: wiring an MCP server like this one up to your actual systems -- your databases, your ticketing tool, your CRM, your internal APIs -- behind the same least-privilege, audited, PII-redacted patterns shown here, and connected to your team's Claude, Cursor, or ChatGPT.

Available Tools

8 tools
add_ticket_commentA

Add a comment to a ticket and return it updated.

Disabled by default (see config/scopes.yaml) -- this is the one write-capable tool in the starter, gated behind the crm:write scope to demonstrate least-privilege-by-default.

Inputs: body (required), author (required), ticket_id (required). Returns: id, status, subject, assignee, +6 more

get_ticketB

Get one support ticket by id, including its comment thread.

Inputs: ticket_id (required). Returns: id, status, subject, assignee, +6 more

list_sql_tablesA

List the tables and columns available in the demo SQL database.

Inputs: no named parameters. Returns: result

list_ticketsA

List support tickets, newest first, optionally filtered by status (open/pending/closed).

Inputs: limit, status. Returns: result

read_docB

Read one markdown document by the path returned from search_docs.

Inputs: path (required). Returns: path, title, content

search_contactsC

Search CRM contacts by name, email, or company.

Inputs: query (required), limit. Returns: result

search_docsB

Search the bundled markdown knowledge base and return the best-matching documents.

Inputs: query (required), limit. Returns: result

sql_queryA

Run a read-only SQL query against the demo database.

Only a single SELECT or WITH...SELECT statement is allowed; writes, DDL, and multi-statement payloads are rejected before they reach SQLite. Use ? placeholders in sql and pass values via params rather than formatting them into the query text. Results are capped at MCP_CONNECT_SQL_MAX_ROWS rows (see truncated in the response).

Inputs: sql (required), params. Returns: rows, columns, row_count, truncated

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action: SQL introspection/query, document search/read, ticket listing/retrieval/commenting, and contact search. There is no meaningful overlap that would cause an agent to select the wrong tool.

    Naming Consistency4/5

    Tool names are consistently snake_case and mostly follow a verb_noun pattern such as list_tickets, get_ticket, search_docs, and add_ticket_comment. sql_query is a minor deviation from the verb_noun convention but remains clear.

    Tool Count5/5

    Eight tools are well within a sensible range for a starter server demonstrating multiple integrations. Each tool has a specific role and the set does not feel bloated or thin.

    Completeness3/5

    The SQL and document surfaces cover their intended read-only workflows, and tickets support listing, retrieval, and commenting. However, ticket lifecycle operations like create/update/close are absent, and contacts only support search with no get/create/update tools.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A production-grade platform that connects AI assistants to internal databases and filesystems through a single authenticated endpoint. It features role-based access control, SSO integration, and built-in tools for querying SQL databases and managing files with full audit logging.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to safely interact with operations systems such as cloud inventory, runbooks, and ticketing while enforcing role-based access, JWT authentication, write confirmation, secret and PII redaction, rate limits, and audit logging.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to safely explore and query MySQL, MariaDB, PostgreSQL, SQLite and StarRocks databases through read-only tools for schema listing, table description, schema search, row sampling, query execution, and plan explanation. Enforces least-privilege accounts, engine-level read-only sessions with timeouts, parsed SQL guardrails, and column masking so runaway or unsafe queries are refused.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to safely explore and query SQL databases through read-only, AST-checked SQL, database-enforced read-only transactions, timeouts, row caps, PII masking, and audit logging.
      MIT