Connect your agent.
Keep the decision.

1. 1

   Enable workspace access

   Open MCP & AI assistants in workspace settings and enable MCP. An active trial, Pro, or lifetime plan is required for tools beyond account status.

2. 2

   Add the server to Codex

   Put this in ~/.codex/config.toml, or in a trusted project's.codex/config.toml for project-only access.

   config.toml4 lines

   [mcp_servers.proposa]
   url = "https://mcp.getproposa.app/mcp"
   auth = "oauth"
   default_tools_approval_mode = "writes"

3. 3

   Restart and authenticate

   Restart the Codex client or begin a new session, then start the OAuth flow.

   Terminal1 lines

   codex mcp login proposa

4. 4

   Verify the connection

   Run /mcp in Codex, then ask: “Use Proposa to show my account status.” The server should expose exactly 13 V1 tools.

1. Context

   Read workspace defaults and authorized commercial knowledge.

   get_workspace_context
2. Client

   Search before copying or creating client details.

   search_clients
3. Draft

   Create revision 1. No public link exists.

   create_proposal_draft
4. Review

   Show totals, recurring fees, warnings, and current revision.

   get_proposal_preview
5. Confirm

   Re-read the proposal and ask the user to approve publication.

   get_proposal
6. Publish

   Activate the secure link, then return it without sending.

   publish_proposal

Use Proposa to draft a proposal from the notes below.

1. Read my workspace context and search for an existing client first.
2. Create a draft only. Show totals, recurring fees, warnings, and revision.
3. Do not publish until I explicitly approve the latest version.
4. After approval, publish it and return the secure client URL.

[Paste the brief here]

If an email or chat tool is also connected, the agent may pass the returnedpublicUrl to it only when the user explicitly requested delivery.

Workspace, client, and knowledge

Proposal reads

Proposal writes

Endpoint

POST https://mcp.getproposa.app/mcp. GET and DELETE return 405.

Discovery

/.well-known/oauth-protected-resource advertises the resource, authorization server, bearer method, and this documentation URL.

Token checks

WorkOS AuthKit JWT, RS256, exact issuer and https://mcp.getproposa.app audience, with expiry validation.

Request bounds

HTTPS is required in production. JSON bodies are limited to 1 MB and tool requests time out after 30 seconds.

Workspace access

Every call requires MCP enabled. Account status remains available with account-only access; other tools require active app access.

Role access

Workspace members can read but cannot write proposals through MCP. Writes require a role above member.

Trial limits

60 calls/minute, 500 calls/day, and 50 writes/day per user and workspace.

Paid limits

120 calls/minute, 2,000 calls/day, and 200 writes/day per user and workspace.

Audit

Reads and writes record request ID, tool, workspace, user, duration, status, resource context, and bounded input metadata.

Tool result envelope

Every tool returns the same envelope in both MCP structuredContent and a JSON text content item. Consumers should prefer structuredContent.

// Success
{
  "ok": true,
  "data": { "...": "tool-specific result" },
  "meta": {
    "requestId": "request-id",
    "workspaceId": "workspace-id"
  }
}

// Failure
{
  "ok": false,
  "error": {
    "code": "REVISION_CONFLICT",
    "message": "The proposal changed. Read it again before applying the update.",
    "retryable": false,
    "details": { "currentRevision": 4 }
  },
  "meta": { "requestId": "request-id", "workspaceId": "workspace-id" }
}