Integrate SanctionsKit with an AI coding agent and MCP

MCP (Model Context Protocol) connects your coding agent to SanctionsKit’s documentation and tools. Once connected, you can ask the agent to add screening to your app and test it with invented data.

You will need Codex installed and a SanctionsKit account for sandbox tests. The sandbox is a test environment with invented records. Follow these three steps; API-key setup and the tool reference come afterward.

• 1. Add the connection.
• 2. Sign in to SanctionsKit.
• 3. Give your agent a task.

Open ~/.codex/config.toml, or create it if needed. Add the block below alongside any existing server entries, then save the file and restart Codex.

[mcp_servers.sanctionskit]
url = "https://www.sanctionskit.com/mcp"

[mcp_servers.sanctionskit.oauth]
client_id = "sanctionskit-codex"
callback_url = "http://127.0.0.1:43127/callback"
callback_port = 43127

Run this command in your terminal. In the browser that opens, sign in to your SanctionsKit account and approve sandbox access for the agent. You do not need to copy an API key.

codex mcp login sanctionskit

Open your application’s repository in Codex, start a new session, and paste this prompt. Add the feature you want, such as checking a supplier when a reviewer clicks a button.

Use the SanctionsKit MCP to add screening to this app.
Read the current docs and follow this project's conventions.
Build a server-side integration and test it with invented sandbox data.
Keep credentials out of the code, conversation, and logs.
Show me the changes and test results. Do not deploy.

Your agent can now read the SanctionsKit docs, adapt the integration to your project, and run an invented sandbox example. Review its proposed tool calls and code changes as you work.

• Server-side code that calls the SanctionsKit REST API.
• A sandbox result with its actual status and evidence, or a clear error to resolve.
• Tests and an explanation of the files changed and any remaining setup.

The quick start uses browser sign-in, called OAuth. It connects the agent to your SanctionsKit workspace with the access you approve. Your AI-client account is separate. You can disconnect the agent on the MCP connections page.

Use a sandbox API key when configuring a compatible client directly or running CI and other automation without a browser. Both methods access the same sandbox tools. Public documentation, schema lookup, and request validation need no account connection.

OpenAI’s authenticated hosted plugin flow uses OAuth. API-key configuration is available in compatible direct MCP clients such as Codex; ChatGPT’s hosted plugin connection does not accept custom API keys.

Use this alternative instead of quick-start steps 1 and 2. Create a sandbox key in API keys. For the complete workflow, grant sources:read, screenings:write, results:read, and usage:read; a production key is not accepted for these tools.

Provide the key to the Codex process as SANCTIONSKIT_SANDBOX_API_KEY through your environment or CI secret store. Replace this server’s OAuth configuration in ~/.codex/config.toml with the block below, then restart Codex and continue at step 3. You do not need to run codex mcp login for this method.

The configuration contains the variable name, never the key itself. Other compatible clients can send the key in the Authorization header as Bearer followed by the sandbox key. Keep credentials out of prompts, committed files, browser code, and logs. Revoke or replace the key in API keys when access should end.

[mcp_servers.sanctionskit]
url = "https://www.sanctionskit.com/mcp"
bearer_token_env_var = "SANCTIONSKIT_SANDBOX_API_KEY"

You can ask your agent for an outcome in plain language; it chooses the relevant tools. Use this reference when you want to inspect or troubleshoot a particular call.

• search_docs: find relevant documentation. Public.
• get_doc: read a documentation page. Public.
• get_api_schema: inspect current API request and response fields. Public.
• validate_screening_request: check request structure without submitting a screening. Public.
• get_profile: identify the connected sandbox account. Sign-in or sandbox key required.
• list_sources: read source metadata. Catalog availability does not change the invented sandbox coverage.
• run_sandbox_screening: submit an invented subject to sandbox@1. Saves evidence, uses sandbox allowance, and may create a review case.
• get_screening_result: retrieve a retained result from the connected sandbox.
• get_usage: check sandbox usage and limits.

Your agent can construct this call for you. If you want to inspect it, the example below shows the arguments for run_sandbox_screening. The request uses an invented Alex Morgan identity, sandbox@1, and synthetic: true. Explicit source selections and counterparty links are not accepted by this tool.

Replace the example idempotency key with a unique value for your operation: 8 to 128 letters, digits, hyphens, or underscores. Reuse the exact same key and request after a network timeout when the outcome is uncertain. Use a new key for a different operation. Read the idempotency guide for details.

Use the returned screening ID with get_screening_result. Inspect the actual status, matches, coverage, and versions. Validation checks request structure; it does not establish source availability or a screening outcome. Keep real customer inputs out of MCP development tests.

{
  "request": {
    "subject": {
      "name": "Alex Morgan",
      "entityType": "person",
      "birthDate": "1984"
    },
    "package": "sandbox@1"
  },
  "idempotencyKey": "mcp-guide-example-001",
  "synthetic": true
}

Use this longer prompt when you want to specify the integration and testing workflow more closely.

Use the SanctionsKit MCP to add server-side screening to this app.

1. Read the quickstart, authentication, screening, errors, and
   idempotency docs. Get the current API schema before writing code.
2. Inspect this project's stack and follow its existing conventions.
3. Check my sandbox profile and usage, and inspect source metadata.
4. Validate an invented person: Alex Morgan, birth year 1984,
   with package sandbox@1. Confirm synthetic:true in the sandbox
   screening tool call. Run one sandbox screening and retrieve it.
   Create one idempotency key for this operation and reuse that key
   with the identical request if a network retry is needed.
5. Build a server-side REST integration. Read its API key from secure
   environment configuration; never print the key or subject inputs.
6. Handle potential_match, no_match, and request failures separately.
   A no-match is limited to selected coverage, not legal clearance.
7. Test success, unavailable coverage, invalid credentials, rate
   limits, timeouts, and idempotent retries with synthetic fixtures.
8. Explain the files changed, tests run, and remaining setup.

Use only synthetic subjects. Do not run production screenings,
change account settings, or deploy the application.

MCP helps your coding agent build the integration. Your application then calls the REST API from its server with its own SanctionsKit API key. It can keep its existing user login; its users do not need an MCP connection. MCP OAuth tokens cannot authenticate REST requests.

MCP account tools are sandbox-only. Before using real data in your application, choose available production sources, configure its production credentials, and complete your normal review and release process. Keep request failures separate from screening outcomes: unavailable requested coverage must remain an explicit failure.

A potential match needs human review. A no-match is limited to the selected coverage and matching rules, not legal clearance. Preserve the returned evidence and warnings. Use the rollout checklist and retention guide to finish the integration.

• Server missing: check the configuration and restart Codex. Run codex mcp list to see configured entries, or /mcp inside a Codex session to inspect active connections.
• Sign-in cannot finish: free local port 43127 and retry. Keep the callback URL and port exactly as shown in the configuration; an unregistered callback will fail.
• Documentation works but sandbox calls fail: sign in with codex mcp login sanctionskit, or check that the client process can read your sandbox API-key environment variable. Confirm the workspace role or key grants the required permission.
• Screening fails: inspect the error code, request structure, and sandbox allowance. Respect rate limits and retry an uncertain request with its original idempotency key. An authentication, coverage, or network error is never a no-match result.
• Using another agent: the server uses remote Streamable HTTP at https://www.sanctionskit.com/mcp. Check that client’s connection and authentication instructions. Direct configuration does not require a directory listing.

Official references

• OpenAI: connect Codex to MCP servers (opens in a new tab)
• OpenAI: Codex MCP commands (opens in a new tab)
• OpenAI: plugin authentication and OAuth (opens in a new tab)