Connections

Promptmark has two sides of MCP integration:

• MCP Server – Exposes Promptmark’s own tools (prompts, collections, playbooks, etc.) so external AI clients like Claude.ai, ChatGPT, or Cursor can interact with your data. Configured in Settings.
• Connections (MCP Client) – Connects Promptmark to external MCP servers so you can browse and use their tools from inside Promptmark.

This guide covers Connections – the MCP client side.

What Connections Do

A connection links Promptmark to a remote MCP server. Once connected, Promptmark discovers the server’s available tools, caches their schemas locally, and makes them available for:

• Browsing – See all tools the server offers, with descriptions and input schemas
• Testing – Execute any tool directly from the tool browser with custom arguments
• Conversations – Attach tools to conversations so the AI model can call them during chat
• Playbooks – Use connected tools in playbook step execution

Each connection tracks its status (connected, error, never connected), the number of discovered tools, and optional token expiry dates.

Adding a Connection

1. Navigate to Connections in the sidebar
2. Click Add Connection
3. Fill in the form:
   • Name – A display name for the connection (e.g., “Civic”, “My Server”)
   • Server URL – The MCP server endpoint URL (must be HTTPS for production servers)
   • Description – Optional notes about what the server provides
   • Authentication – How to authenticate with the server (see below)
   • Token Expiry – Optional date when the credential needs refreshing
4. Click Add Connection

After saving, click Test on the connection card to verify connectivity and discover tools.

Authentication Types

Connections support five authentication methods:

Credentials are encrypted at rest using AES-256 (AES-GCM) and are never exposed in API responses or logs.

Custom Headers

For the Custom Headers type, provide a JSON object with string keys and values:

{"Authorization": "Bearer my-token", "X-Custom-Header": "value"}

All custom headers are merged into every request to the MCP server.

Civic Connections

Civic is a featured integration that acts as an MCP hub – a single connection that provides access to tools from 85+ MCP servers behind one endpoint. Instead of configuring individual connections to Google, Slack, GitHub, and every other service you use, you connect to Civic once and get tools for all of them.

How Civic Differs from Generic Connections

A standard MCP connection links Promptmark to one server with one set of tools. Civic is fundamentally different:

Available Services

Civic aggregates tools across major categories:

• Productivity – Google Workspace (Gmail, Calendar, Drive, Sheets, Docs), Microsoft 365, Notion
• Communication – Slack, Discord, Microsoft Teams
• Development – GitHub, GitLab, Jira, Linear, Sentry
• Finance – Stripe, QuickBooks
• CRM & Marketing – HubSpot, Salesforce, Mailchimp
• Storage & Files – Google Drive, Dropbox, Box
• Utilities – Timestamp conversion, memory storage, date/time tools

The full list grows as Civic onboards new providers. You do not need to reconfigure your connection when new services are added – they appear automatically in your tool list after a refresh.

Connecting to Civic

1. On the Connections page, click Connect Civic on the featured card (shown when you have no existing Civic connection)
2. Choose your authentication method — Bearer Token (recommended) or OAuth if you have OAuth credentials
3. Paste the API token from your Civic dashboard
4. Optionally set the token expiry date (Civic tokens expire after 30 days)
5. Click Connect

The connection is created with the server URL pre-filled to https://app.civic.com/hub/mcp.

Civic Auth Flow

Civic handles OAuth authorization for each underlying service on your behalf. The first time the AI calls a tool for a service you haven’t authorized yet (for example, reading your Gmail), the conversation pauses and presents an authorization card. Here is how the flow works:

1. The AI requests a tool call – for example, gmail_search to find recent emails
2. Civic responds with an auth requirement – the tool needs access to your Google account
3. Promptmark shows an authorization card in the conversation with a link to Civic’s auth page
4. You click the link – a popup opens where you grant Civic access to the specific service (e.g., Google)
5. Promptmark polls for approval – it checks every 1.5 seconds whether you’ve completed the flow
6. The conversation resumes automatically – once approved, Promptmark calls continue_job on Civic to resume the original tool operation, and the AI receives the result

The polling timeout is 2 minutes. If you don’t complete the authorization within that window, the request is cancelled and you can retry by sending another message. Some operations may require chained authorization (for example, a tool that accesses two services) – Promptmark handles up to 10 chained auth cycles per tool call.

This flow uses the civic:rest-auth protocol extension. Civic’s auth endpoint is validated against SSRF protections before polling begins.

Auto-Attach

When you create a new conversation and have an active Civic connection, Promptmark automatically pre-selects a set of default Civic tools in the tool picker:

• help – General assistance tool
• load-skill – Load a Civic skill
• store-save – Persistent storage
• continue_job – Resume operations after auth
• convert-timestamp – Timestamp conversion utility
• get-current-datetime – Current date and time
• memory-access-memory – Memory access tool

These defaults are pre-checked in the tool picker, not silently injected. You can uncheck any of them before starting the conversation, or add additional tools from the full Civic tool catalog.

Browsing Tools

After testing a connection, click the tool count badge on the connection card to open the Tool Browser.

The tool browser shows:

• Tool name – The MCP tool identifier
• Description – What the tool does
• Parameter count – Number of input parameters
• Favorite status – Mark tools as favorites for quick access

Use the search bar to filter tools by name or description. Click Refresh to re-fetch the tool list from the remote server.

Testing Tools

Click any tool in the browser to open the Tool Detail view. This shows:

• The full tool description
• The complete input schema (JSON Schema format)
• A Try it form where you can enter JSON arguments and execute the tool

Tool execution streams results via SSE, so you see output as it arrives. Each execution is logged in the audit trail with latency, status, and input/output payloads.

Favoriting Tools

Mark frequently used tools as favorites from the tool detail view. Favorited tools appear prominently in the tool picker when attaching tools to conversations.

Using Tools in Conversations

Connected tools can be attached to conversations, enabling the AI model to call them during chat.

Attaching Tools

1. Open a conversation
2. Use the tool picker to browse available tools from your connections
3. Select tools to attach

Attached tools are sent to the AI model as tool definitions. When the model decides to call a tool, Promptmark executes it on the remote MCP server and feeds the result back into the conversation.

Tool Execution Loop

When the AI requests a tool call:

1. Promptmark connects to the remote MCP server
2. Executes the requested tool with the model’s arguments
3. Returns the result to the model
4. The model processes the result and continues its response

This loop can repeat up to 10 times per message (configurable). Each tool call has a 60-second timeout.

Using Tools in Playbooks

Playbooks can reference connected tools through the @prompt(mcp:connection_id/tool_name) scheme. The playbook engine executes the tool during step execution and incorporates the result into the workflow.

Connection Status

Each connection card shows its current status:

Token expiry warnings appear when a credential is within 7 days of expiration, or has already expired.

Editing and Deleting

• Edit – Click the edit button on a connection card to update its name, URL, description, auth settings, or token expiry
• Delete – Click the delete button to remove a connection and its cached tools (soft delete)

When you update a connection’s URL or authentication, the pooled session is automatically closed so the next operation uses fresh credentials.

REST API

Connections are also manageable via the REST API under /api/mcp/connections.

All endpoints require authentication via JWT (cookie or Authorization: Bearer header).

MCP Tools

Connections are fully manageable via Promptmark’s MCP server tools. AI assistants connected to your Promptmark MCP server can create, browse, and execute tools on your behalf.

For full MCP tool schemas, see the MCP Reference.

What’s Next

• MCP Setup – Configure the MCP Server side (exposing Promptmark’s tools to AI clients)
• MCP Reference – Full schemas for connection MCP tools
• Conversations – Using connected tools in conversations
• Playbooks – Multi-step workflows that can use connected tools