# Returns Dev MCP Source: https://developer.avalara.com/products/returns/integration-guides/managed-returns/wbj5773302111505/ Guide: Avalara Managed Returns API (U.S. and Canada) # Returns Dev MCP Use Returns Dev MCP to build and validate Managed Returns API integrations in an AI-powered IDE by exploring product context, schemas, patterns, and sandbox queries. Returns Dev MCP is an AI-powered development toolkit that accelerates building applications on top of the Avalara Managed Returns API. Instead of manually reading documentation and exploring GraphQL schemas, you can use natural language prompts in an AI-powered IDE like Cursor to generate validated code. Note - Returns Dev MCP connects to the sandbox environment for safe development and testing. - Returns Dev MCP isn’t required for integrating with the Managed Returns API. - This isn’t the standard MCP offering, and it's intended only for UI development and testing purposes. Returns Dev MCP provides 5 specialized tools that work together: - Discover the product context: Discover available products and load their context. - Understand domain rules: Explore entities, compliance workflows, and relationships. - Explore GraphQL schemas: Inspect queries, mutations, object types, and field signatures. - Learn integration patterns: Learn best practices for authentication, variables, mutations, and error handling. - Validate queries: Test queries and mutations directly against the sandbox environment before deployment. Specify the target product by passing the `product_name` argument to the developer tools. You need to pass `managed_returns_us` it covers sales and use tax returns for U.S. jurisdictions, including firm and client provisioning, company setup, filing calendar configuration, and the return filing lifecycle. Follow this sequential workflow when building features in your IDE: 1. `dev_get_product_context`: Discover available products and establish context for your target product. 2. `dev_search_docs`: Review business requirements and domain context for your workflow. 3. `dev_introspect_schema`: Explore available GraphQL queries, mutations, and input types. 4. `dev_learn_patterns`: Learn the best practices for handling errors and structuring mutations. 5. `dev_validate_query`: Validate your GraphQL operation against sandbox data before connecting it to your UI. ## Configure Dev MCP in your IDE **Prerequisites**: - An AI-powered IDE supporting Model Context Protocol (MCP), such as Cursor. - A valid Avalara Managed Returns API JWT token for the Sandbox environment. Add the following configuration to your IDE's MCP configuration file (for example, ~/.cursor/mcp.json): ``` { "avalara-returns": { "transport": "http", "url": "https://mcp.sbx.avalara.com/returns", "headers": { "Authorization": "Bearer jwt_token_here", "X-Dev-Tools": "true" } } } ``` Replace `jwt_token_here` with your actual SBX (Sandbox) JWT token. After saving the file, restart your IDE and confirm that `avalara-returns` appears under Installed MCP Servers and that all 5 tools are available. ## Tools The available tools are: Tool Description `dev_get_product_context` Returns the context for a product, including its description, documentation availability, and recommended workflow. **Parameters**: `product_name` (optional): set to `managed_returns_us` to cover sales and use tax returns for U.S. jurisdictions. Omit it to list all available products. `dev_search_docs` Retrieves business documentation covering entities, workflows, and lifecycle relationships. Use this tool to understand the business context before implementing any feature. **Parameters**: `product_name` (required): set to `managed_returns_us` to cover sales and use tax returns for U.S. jurisdictions. `dev_learn_patterns` Returns API implementation patterns, best practices, and error-handling techniques. Use this tool to learn correct patterns before writing queries or mutations. **Parameters**: - `product_name` (required): set to `managed_returns_us` to cover sales and use tax returns for U.S. jurisdictions. - `topic` (optional): `auth`, `variables`, `mutations`, or `errors` `dev_introspect_schema` Inspects the GraphQL schema with 3 modes: root operations (no parameters), type inspection (`type_name`), or operation signature (`operation_name`). Use this tool to discover available operations or get detailed field information. **Parameters**: - `product_name` (required): set to `managed_returns_us` to cover sales and use tax returns for U.S. jurisdictions. - `type_name` (optional): Returns the full definition for the named type. - `operation_name` (optional): Returns the complete signature for the named operation. `dev_validate_query` Executes and validates a GraphQL query or mutation against the sandbox environment before connecting to your UI. Use this tool to validate the query before presenting it to users. **Parameters**: - `query` (required): The GraphQL query or mutation string. - `product_name` (required): set to `managed_returns_us` to cover sales and use tax returns for U.S. jurisdictions. - `variables` (optional): Variables object. ## Important considerations - All queries executed via `dev_validate_query` run against staging data - Schema introspection results are cached for performance (1-hour TTL) - JWT tokens must have appropriate scopes for the operations you're building - A single Dev MCP connection serves all supported products. Select the product per call using the `product_name` argument rather than configuring a separate connection ## Related information - To understand the core entities before building, see [Avalara Managed Returns API core concepts and architecture](/managed-returns/hzm7157104844927/ "Learn the core objects and relationships in Avalara Managed Returns API, including accounts, companies, firm-client linkage, filing calendars, and filings."). - To connect directly using the standard GraphQL API, see [Connect to the Avalara Managed Returns API](/managed-returns/tvm4716382896853/).