Agent integrations

Plain-text connection instructions

Choose a connection path

Terminal Tax connects tax agents to a secure review and submission workflow. Integration access is restricted to authorized sessions.

First identify the actual host and available tools. Codex CLI, a desktop app and a browser chat have different connection capabilities. A missing tool or plugin-directory result means the connection is not configured; it does not establish that this host cannot connect.

If a Terminal Tax tool is already connected, use it. Otherwise, with the person's authorization, use the host's supported remote-MCP setup. A shell-capable agent can configure its own client; an agent with authenticated outbound HTTPS can use the same MCP protocol directly. A search-only chat needs its host's supported connector setup first.

Configure the connection yourself when your actual tools and permissions allow it. Ask the person only for an authorization or host control you cannot operate. Never claim success until initialization and tools/list actually work. If blocked, report the attempted operation and exact missing capability; do not send the person through unrelated app settings.

No Terminal Tax package, local server or API key is required. Do not ask the person to copy return JSON, tokens or commands between applications. A connection does not authorize a tax submission.

Hosted endpoint and discovery

Remote MCP: https://terminal-tax-ats-ceremony.vercel.app/v1/hosted-mcp

OAuth authorization-server metadata: https://terminal-tax-ats-ceremony.vercel.app/.well-known/oauth-authorization-server

OAuth protected-resource metadata: https://terminal-tax-ats-ceremony.vercel.app/.well-known/oauth-protected-resource/v1/hosted-mcp

This is a Streamable HTTP MCP endpoint, not an unauthenticated return-upload API. A browser GET can return 405; an unauthenticated MCP POST returns 401 and points to authorization metadata. Neither response alone means the service is unavailable.

Codex CLI with shell access

Check the installed host using codex mcp --help and codex mcp list. When the person has asked to connect, use codex mcp add to register the remote URL and codex mcp login for OAuth, using this session's existing configuration scope. These are Codex CLI commands; ChatGPT account settings are not a prerequisite for a Codex CLI connection.

The normal commands are shown below. Preserve any existing Terminal Tax configuration rather than overwriting it blindly. OAuth approval is separate from filing consent and signing.

codex mcp add terminal-tax --url https://terminal-tax-ats-ceremony.vercel.app/v1/hosted-mcp
codex mcp login terminal-tax
codex mcp list
  1. Open the authorization URL through the host's supported flow and let the person approve any required access. Keep OAuth credentials in the client's credential storage, not in the conversation.
  2. After setup, inspect the active tool list. Configuration changes do not prove a running conversation has refreshed its tools; check the installed host's supported refresh or resume behavior.
  3. If the current host cannot refresh its native tool list but this agent has outbound HTTPS and an authorized MCP client session, use the direct connection below in the same task. Otherwise preserve the conversation through the host's supported resume flow and explain the one remaining host step without asking the person to repeat their tax interview.

Other desktop and browser chat hosts

Use the actual host's supported Add remote MCP server or connector flow with the endpoint above, then complete OAuth. A listing in a plugin directory is not required for hosts that support custom remote MCP servers.

Do not assume browser-chat settings apply to a terminal agent, or that every browser chat supports custom tools. If the host provides neither connector management nor authenticated outbound requests, give the person that host's precise supported connection step. Public documentation cannot add tools or override host permissions.

After connecting, verify the three tools through tools/list. Use the host's documented refresh or resume mechanism only if necessary; do not assert that every host requires a new conversation.

Codex connection reference: https://developers.openai.com/codex/mcp/

Direct HTTPS from an agent's existing tools

A native MCP tool registration is not required to speak the protocol: an agent with a supported OAuth client, secure credential storage and outbound HTTPS can use the same authenticated endpoint. This changes the client transport, not consent, access or destination controls. Prefer an existing MCP client that handles OAuth and Streamable HTTP correctly.

Discover authorization through the protected-resource and authorization-server metadata. Complete OAuth authorization-code flow with PKCE S256 and the advertised resource and registration rules. Use an actual callback supported by your client, and let the person approve access in the browser. Do not invent an authorization token or send taxpayer information while connecting.

Send each JSON-RPC message as an HTTP POST with Content-Type: application/json and Accept: application/json, text/event-stream. The authenticated client supplies the Authorization header. Process either a JSON response or SSE data events; do not treat an SSE envelope as the tool result.

First send initialize with a supported protocol version and client capabilities. Use the server's negotiated version in MCP-Protocol-Version on later requests. If initialization returns Mcp-Session-Id, retain and send it on later requests. Send notifications/initialized, then tools/list, then tools/call using the returned schemas. Do not assume a connection or a successful draft is an IRS acceptance.

MCP transport reference: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

Filing workflow after connection

Use the authenticated tool descriptions and returned schema as the authoritative contract for the current session.

  1. Only after the person explicitly asks to file, call create_filing_session with no arguments. This creates an empty reservation. Give the person the returned link and stop; do not transmit return information yet.
  2. The person opens that link, acknowledges the privacy notice and gives the separate sensitive-tax-data permission. Wait for them to return to the same conversation, confirm both actions, and explicitly ask to continue.
  3. Call continue_filing_session with requestPacketSchema=true. The service independently checks both browser permissions before returning the schema.
  4. Use that schema to call continue_filing_session with completedReturnPacketJson and packetSchemaSha256. Supply only facts and treatments explicitly provided by the person; do not infer missing answers or substitute a tax year. Build the JSON inside the tool call; do not ask the person to copy or edit it.
  5. The person uses the same hosted session to complete all required identity, possession, payment, review and signature steps personally. The agent never supplies or relays their signing PIN or prior-year authentication values.
  6. Call get_filing_status with no arguments when the person asks about this filing, or when the authenticated tool contract requires resolving it. Report the returned destination-specific result accurately; completing review is not evidence of IRS acceptance.

Scope and support

The authorized session determines destination and supported return scope. An unmet requirement stops the workflow. There is no public return-upload form.

Privacy: https://terminal.tax/privacy-notice

Terms: https://terminal.tax/terms

Support: https://terminal.tax/support