# PostalForm integration kit

The endpoint is `https://postalform.com/mcp` (streamable HTTP). Hosted MCP discovery needs no API key. This kit exposes discovery, unpaid drafts and order status; its Python allowlist excludes payment operations. Documents and addresses are transmitted to PostalForm when a draft tool is invoked.

Use [live instructions](https://postalform.com/skill.md), [form references](https://postalform.com/developers/forms), [pricing](https://postalform.com/pricing), and [mailing limits](https://postalform.com/mailing-limits). This folder is a distributable integration reference, not an automatically installed repository skill.

## Python setup

Download the Python files together into one directory. Use Python 3.11 or later and create a virtual environment:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
```

The core adapter uses the [official MCP Python SDK 1.x API](https://github.com/modelcontextprotocol/python-sdk/tree/v1.20.0). Pin dependencies in your deployment's lock file after testing. Imports alone do not contact PostalForm. A tool call opens a connection, initializes MCP, invokes once and closes the connection. Transport failures are surfaced rather than silently retried; an interrupted draft call may have created a draft.

## Claude Desktop and remote clients

For a client that accepts remote HTTP MCP servers, use `mcp-remote.json`; adapt the outer config format to the client. For a local stdio client, merge the `mcpServers.postalform` entry from `claude-desktop.json` into the client's configuration, replacing both absolute paths with your virtual-environment Python and `mcp_stdio.py` paths. The local server exposes `postalform_tools` to retrieve live schemas and `postalform_call` to invoke an allowed tool. Keep the client's confirmation controls enabled for document and address disclosure.

## LangChain

Install `langchain-core` in the same environment. Import `POSTALFORM_TOOLS` from `langchain_tools.py` and pass them to your agent's tools. Both tools are asynchronous; invoke through the framework's async path. The implementation uses the documented [LangChain tool decorator](https://docs.langchain.com/oss/python/langchain/tools).

```python
from langchain_tools import POSTALFORM_TOOLS

schemas = await POSTALFORM_TOOLS[0].ainvoke({})
# Construct arguments from the selected live schema, then invoke the draft tool.
```

## CrewAI

Install `crewai` in the same environment. Import `PostalFormTools` and `PostalFormCall` from `crewai_tools.py`, then add their instances to your Agent's `tools`. The adapter implements the documented [CrewAI BaseTool interface](https://docs.crewai.com/en/concepts/tools) with sync and async entry points. Use the async entry point when already inside an event loop.

```python
from crewai_tools import PostalFormTools, PostalFormCall

tools = [PostalFormTools(), PostalFormCall()]
```

## OpenAI Custom GPT Actions

Import `https://postalform.com/integrations/postalform/openai-actions.json` as the Actions schema. It is generated from PostalForm's runtime OpenAPI during the website build. This deliberately limited profile includes form discovery, form schema retrieval and mailing validation. It cannot create a paid order, complete checkout or send mail. Validation is marked consequential because it transmits document and address data. For unpaid draft creation with hosted checkout, use the MCP integration instead.

## Distribution

`SKILL.md` and `prompts.md` are ready to include in an approved client configuration. Registry metadata is available at `https://postalform.com/.well-known/mcp/server.json`. Directory submission is a separate publication action; the presence of this kit does not imply registry acceptance or an endorsement. Public downloads are copied from this directory during `seo:generate`; no private credentials or repository configuration belong here.