# Any MCP client (/docs/mcp/clients/any-client) Kyoto is a remote MCP server. Any app that supports remote MCP servers can use it. | Setting | Value | | -------------- | -------------------------- | | URL | `https://mcp.heykyoto.com` | | Transport | Streamable HTTP | | Authentication | None | ## Cursor [#cursor] Open Cursor's MCP server settings and add a server. Or add Kyoto to `~/.cursor/mcp.json`: ```json { "mcpServers": { "kyoto": { "url": "https://mcp.heykyoto.com" } } } ``` ## VS Code [#vs-code] Add Kyoto to `.vscode/mcp.json` in your workspace: ```json { "servers": { "kyoto": { "type": "http", "url": "https://mcp.heykyoto.com" } } } ``` ## Apps that support only local servers [#apps-that-support-only-local-servers] Some apps can only start a local server. Use `mcp-remote` to connect them to Kyoto: ```json { "mcpServers": { "kyoto": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.heykyoto.com"] } } } ``` ## Test that it works [#test-that-it-works] Start a new chat and ask: > Use Kyoto. I entered the US on March 15, 2023 as a tourist, changed to F-1 student status on November 15, 2023, and I'm still a student. I follow my visa rules and have not applied for a green card. I'm single. Am I a US tax resident for 2025? Kyoto may ask a question or two first. The answer should say that you are a **nonresident** for 2025 and that you must send **Form 8843**, the statement for students and exchange visitors. ## Next steps [#next-steps] The tools, how they work together, and example prompts. # ChatGPT (/docs/mcp/clients/chatgpt) ## Connect ChatGPT [#connect-chatgpt] ### Turn on developer mode [#turn-on-developer-mode] Go to **Settings**, then **Apps**, then **Advanced settings**, and turn on **Developer mode**. ### Create a connector [#create-a-connector] In **Settings**, open **Apps** and click **Create**. ### Enter the details [#enter-the-details] * **Name:** `Kyoto` * **MCP server URL:** `https://mcp.heykyoto.com` * **Authentication:** `No authentication` Click **Create**. ### Start a chat [#start-a-chat] Select Kyoto from the developer mode tools in the composer, then ask your question. Developer mode is available on the web on paid ChatGPT plans. ChatGPT Free does not have developer mode. On the Free plan, connect Kyoto to [Claude](/docs/mcp/clients/claude) or to [another MCP client](/docs/mcp/clients/any-client) instead. ## Test that it works [#test-that-it-works] Start a new chat and ask: > Use Kyoto. I entered the US on March 15, 2023 as a tourist, changed to F-1 student status on November 15, 2023, and I'm still a student. I follow my visa rules and have not applied for a green card. I'm single. Am I a US tax resident for 2025? Kyoto may ask a question or two first. The answer should say that you are a **nonresident** for 2025 and that you must send **Form 8843**, the statement for students and exchange visitors. ## Next steps [#next-steps] The tools, how they work together, and example prompts. # Claude (/docs/mcp/clients/claude) ## Claude.ai and the Claude desktop app [#claudeai-and-the-claude-desktop-app] ### Open Connectors [#open-connectors] Click **Customize**, then click **Connectors**. ### Add a custom connector [#add-a-custom-connector] Click the **+** button and select **Add custom connector**. ### Enter the details [#enter-the-details] Enter the name as `Kyoto` and the URL as `https://mcp.heykyoto.com`, then click **Add**. ### Start a chat [#start-a-chat] Turn on Kyoto from the **+** menu in a chat, then ask your question. The Claude desktop app does not read remote servers from `claude_desktop_config.json`. Add them through **Connectors**. ## Claude Code [#claude-code] Run this command in your terminal: ```bash claude mcp add --transport http kyoto https://mcp.heykyoto.com ``` Run `/mcp` in a Claude Code session to see that Kyoto is connected. ## Test that it works [#test-that-it-works] Start a new chat and ask: > Use Kyoto. I entered the US on March 15, 2023 as a tourist, changed to F-1 student status on November 15, 2023, and I'm still a student. I follow my visa rules and have not applied for a green card. I'm single. Am I a US tax resident for 2025? Kyoto may ask a question or two first. The answer should say that you are a **nonresident** for 2025 and that you must send **Form 8843**, the statement for students and exchange visitors. ## Next steps [#next-steps] The tools, how they work together, and example prompts. # Kyoto MCP Server (/docs/mcp) The Kyoto MCP server gives your AI assistant Kyoto's tax tools. Connect it to ChatGPT or Claude, then ask your questions in plain words. Kyoto's engine does the work and your assistant explains the answer. The tools are free and need no Kyoto account. Add the server URL to your assistant and start asking. The server URL is: ## Why use Kyoto [#why-use-kyoto] * **The rules, not a guess.** Residency rules are detailed: day counts over three years, exempt years for students and scholars, and choices with deadlines. Kyoto's engine applies the Internal Revenue Code, the Treasury regulations and IRS Publication 519, and counts the days itself. Your assistant does not have to work out the law on its own, and AI can make mistakes with math. In a [study of frontier AI models](https://arxiv.org/abs/2507.16126), the best model calculated less than a third of simple federal returns correctly. * **The same answer every time.** The engine is rules-based, so the same facts always give the same result. Its results are checked against 200+ cases. * **Your facts stay yours.** No language model at Kyoto reads the facts you give, and the free tool stores no facts or answers. If you later engage Kyoto to prepare your return, we keep the information you share there under your engagement terms and consents. See our [privacy policy](https://heykyoto.com/privacy#ai-assistants). ## What your assistant can do with Kyoto [#what-your-assistant-can-do-with-kyoto] * Work out each person's US tax residency for 2026, or for 2025 when needed, with the dates it starts and ends * Say which return applies if a return is due * Say whether the person must send the statement for students and exchange visitors (Form 8843) * List the choices that are open, what each one needs, and its deadline * Say which signed statements must go with the return * Say which tax ID number each person uses, or must apply for * Answer for 2026 from travel plans, and give the days counted so far and the last day the person can leave ## What Kyoto does not do [#what-kyoto-does-not-do] * It does not answer immigration questions, such as visas or green card applications. * For some cases it says that it cannot decide yet, for example when a choice is up to you or a fact is not known yet. Your assistant then explains what you can do. ## Connect your AI assistant [#connect-your-ai-assistant] Pick your assistant for the setup steps. Add Kyoto as a connector in developer mode. Claude.ai, the Claude desktop app and Claude Code. Cursor, VS Code and other apps that support remote MCP servers. ## Available tools [#available-tools] The server has 3 tools. All of them are free. Each tool works for every topic that Kyoto can compute; today the topic is US tax residency (`residency`). | Tool | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kyoto_guide` | Start here. It lists the topics Kyoto can compute today and, for each, what Kyoto answers, where each fact comes from, and what the assistant must not decide for the person. Your assistant reads it first. | | `kyoto_input_schema` | The input format for one topic and tax year (2026 when you give none). Each field says what the fact is and which document holds it. To get one section only, give its id from the section list in `kyoto_guide` as `section`. | | `kyoto_determine` | Computes the answer for one topic from the person's raw facts. For residency it works out each person's US tax residency, lists any fact that is still missing, says when Kyoto cannot decide a case, and for 2026 can answer from plans. | ## How the tools work together [#how-the-tools-work-together] Your assistant uses the tools in this order: ### Read the guide [#read-the-guide] `kyoto_guide` tells the assistant which topics Kyoto answers and the rules it must follow. ### Get the input format [#get-the-input-format] `kyoto_input_schema` gives the facts to collect for the topic and tax year. Each fact names the document that holds it, such as the I-94 travel history. ### Collect the facts [#collect-the-facts] The assistant looks in your documents first. It then asks you for every fact that is still missing, in one message. ### Get the answer [#get-the-answer] `kyoto_determine` returns the result. If a fact is missing, the assistant asks for it and calls the tool again. The most useful document is your record of US entries and exits, called the I-94 travel history. You can download it from the [US Customs and Border Protection I-94 website](https://i94.cbp.dhs.gov). Last year's tax return also helps. ## Example prompts [#example-prompts] **Residency status** * "I moved to the US on an H-1B in March 2026. Will I be a resident for tax purposes this year?" * "I'm on an F-1 visa. Do I need to file Form 8843 for 2025?" * "My spouse and I arrived at different times. Can we file a joint return?" **Just arrived** * "I started an F-1 program in September 2026. Will I be a US tax resident this year?" **Plans for 2026** * "I plan to leave the US on 15 August 2026. Will I still be a resident for 2026?" * "How many more days can I spend in the US this year before I become a resident?" **Tax ID numbers** * "My spouse has no Social Security number. Which tax ID do they need?" **Choices and deadlines** * "Which residency choices are open to me, and when is each one due?" ## Troubleshooting [#troubleshooting] **Kyoto does not appear in my assistant.** Start a new chat. In ChatGPT, select Kyoto from the developer mode tools in the composer. In Claude, turn Kyoto on from the **+** menu. If it still does not appear, remove the connector and add it again. **The assistant answers without using Kyoto.** Ask it directly, for example: "Use Kyoto to work out my US tax residency." **The assistant uses old Kyoto tools.** Assistants keep a copy of the tool list. Remove the Kyoto connector and add it again, then start a new chat. **Kyoto says it is getting too many requests.** Kyoto has a fair-use limit. Wait for the time that Kyoto gives, then ask again. **Kyoto says it cannot decide yet.** Some cases depend on a choice that only you can make, on a fact that is not known yet, or on rules Kyoto does not cover yet. Your assistant explains which one applies and what you can do. ## Important notes [#important-notes] * Kyoto answers for 2026 by default, and for 2025 when you ask about 2025, including a return filed on extension, late or amended, and the first-year choice for 2025. * An answer for 2026 that uses plans is marked as projected. It can change when your travel or status changes. * Kyoto also prepares US tax returns for people who are new to the US. [Sign up for early access](https://heykyoto.com). ## Next steps [#next-steps] Add Kyoto to ChatGPT in a few steps. Add Kyoto to Claude.ai, the desktop app or Claude Code. Cursor, VS Code and a config for other apps. The whole docs site as plain text for your assistant.