MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/vaults.py:319-357 (handler)

  The primary handler function for the paradex_vault_account_summary tool. It accepts a vault_address parameter, calls the Paradex API via api_call to retrieve the account summary, validates the JSON response using a Pydantic TypeAdapter for list[VaultAccountSummary], handles errors, and returns the validated summary list.
  @server.tool(name="paradex_vault_account_summary") async def get_vault_account_summary( vault_address: Annotated[ str, Field(description="The address of the vault to get account summary for.") ], ) -> list[VaultAccountSummary]: """ Get a comprehensive overview of a vault's trading account status. Use this tool when you need to: - Check account health and available margin - Monitor total exposure and leverage - Understand risk metrics and account status - Assess trading capacity before placing new orders - Get a consolidated view of account performance This provides essential information about account standing and trading capacity to inform risk management decisions. Example use cases: - Checking available margin before placing new orders - Monitoring account health during market volatility - Assessing total exposure across all markets - Understanding maintenance margin requirements - Planning position adjustments based on account metrics """ try: client = await get_paradex_client() response = await api_call( client, "vaults/account-summary", params={"address": vault_address} ) if "error" in response: raise Exception(response["error"]) results = response["results"] summary = vault_account_summary_adapter.validate_python(results) return summary except Exception as e: logger.error(f"Error fetching account summary for vault {vault_address}: {e!s}") raise e
• src/mcp_paradex/models.py:385-399 (schema)

  Pydantic BaseModel defining the output schema for the tool response. Specifies fields like address, deposited_amount, vtoken_amount, total_roi, total_pnl, and created_at with descriptions and types.
  class VaultAccountSummary(BaseModel): """Model representing an account summary for a vault.""" address: Annotated[str, Field(description="Contract address of the vault")] deposited_amount: Annotated[ str, Field(description="Amount deposited on the vault by the user in USDC") ] vtoken_amount: Annotated[str, Field(description="Amount of vault tokens owned by the user")] total_roi: Annotated[ str, Field(description="Total ROI realized by the user in percentage, i.e. 0.1 means 10%") ] total_pnl: Annotated[str, Field(description="Total P&L realized by the user in USD")] created_at: Annotated[ int, Field(description="Unix timestamp in milliseconds of when the user joined the vault") ]
• src/mcp_paradex/tools/vaults.py:316-316 (helper)

  Pydantic TypeAdapter used in the handler to validate the API response as a list of VaultAccountSummary objects.
  vault_account_summary_adapter = TypeAdapter(list[VaultAccountSummary])
• src/mcp_paradex/tools/vaults.py:319-319 (registration)

  Decorator that registers the get_vault_account_summary function as an MCP tool with the specified name.
  @server.tool(name="paradex_vault_account_summary")